All Things Linux

The official website for All Things Linux (allthingslinux.org).

🚀 Quick Start

# Clone & setup
git clone https://github.com/allthingslinux/allthingslinux.git
cd allthingslinux
pnpm install

# Setup Cloudflare bindings (R2, KV) - IMPORTANT: Update wrangler.jsonc with KV ID from output
pnpm run setup:bindings

# Start development
pnpm run dev:all

# Development with all services
pnpm run dev:all  # Next.js + Wrangler + Trigger.dev

# Development with all services
pnpm run dev:all  # Next.js + Wrangler + Trigger.dev

Open http://localhost:3000 for Next.js dev, or http://localhost:8788 for Cloudflare Workers simulation.

📋 Tech Stack

Framework: Next.js 15 (App Router)
Styling: Tailwind CSS
Content: Contentlayer (MDX blogs)
Deployment: Cloudflare Workers + OpenNext (^1.14.7)
- Multi-worker architecture: Separate dev and prod environments
- PR deployments target dev environment only
Background Jobs: Trigger.dev
Package Manager: pnpm

📋 Prerequisites

Node.js (see package.json engines field)
pnpm - npm install -g pnpm
Cloudflare Account (for deployments & secrets)
Trigger.dev Account (for background jobs)

🛠️ Setup & Development

1. Clone & Install

git clone https://github.com/allthingslinux/allthingslinux.git
```bash
cd allthingslinux
pnpm install

2. Setup Cloudflare Bindings

# Create R2 buckets and KV namespaces
pnpm run setup:bindings

# IMPORTANT: Update wrangler.jsonc with the KV namespace ID shown in the script output

3. Configure Secrets

For local development, create .env.secrets.dev and .env.secrets.prod files (these are gitignored):

# Create .env.secrets.dev for local development (sandbox credentials)
# Create .env.secrets.prod for production credentials
# Add your secrets following the format: KEY=value (one per line)

For CI/CD, secrets are managed via GitHub Environments (see Deployment section below).

Upload secrets to Cloudflare manually (when needed):

```bash
pnpm run secrets:dev   # Upload dev/sandbox secrets to dev worker
pnpm run secrets:prod  # Upload production secrets to prod worker

4. Start Development

pnpm run dev:all  # Next.js + Wrangler + Trigger.dev

URLs:

Next.js Dev: http://localhost:3000 (with HMR)
Workers Sim: http://localhost:8788 (Cloudflare environment)

🚀 Deployment

Automatic Deployments (GitHub Actions CI/CD)

GitHub Actions with GitHub Environments - Automatic deployments on push/PR:

Branch	Environment	URL
`main`	Production	allthingslinux.org
PR/other	Development	allthingslinux.dev

Quick setup:

Create GitHub Environments: dev and prod (Settings → Environments)
Add secrets and variables to each environment:
- Secrets (sensitive): QUICKBOOKS_CLIENT_ID, QUICKBOOKS_CLIENT_SECRET, QUICKBOOKS_REFRESH_TOKEN, QUICKBOOKS_REALM_ID, QUICKBOOKS_ADMIN_KEY, GITHUB_TOKEN, MONDAY_API_KEY, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, TRIGGER_SECRET_KEY
- Variables (non-sensitive): MONDAY_BOARD_ID, DISCORD_WEBHOOK_URL, QUICKBOOKS_ENVIRONMENT
Push to any branch → Auto-deploys to development environment
Merge to main → Auto-deploys to production environment

See docs/integrations/quickbooks.md for detailed QuickBooks integration setup.

Architecture: Separate Cloudflare Workers for dev/prod with isolated R2/KV bindings. .github/workflows/deploy.yml automatically handles branch detection and deploys to appropriate worker.

Manual Deployments

Quick Deploy (Immediate)

pnpm run deploy:dev     # Deploy immediately to dev
```bash
pnpm run deploy:prod    # Deploy immediately to prod
pnpm run deploy         # Quick production deploy

Version Management (Safer Production)

pnpm run version:upload # Upload version to production
```bash
pnpm run version:list   # List all versions
pnpm run version:deploy # Deploy latest version

Benefits:

Rollback capability: Quickly revert to previous versions
Audit trail: Track deployment history
Risk reduction: Test versions before full deployment

Build Process

# Full production build (Next.js + OpenNext for Cloudflare)
pnpm run build:all

# Next.js build only
pnpm run build

# Preview build locally (tests the Cloudflare Workers build)
pnpm run preview           # Standard preview
pnpm run preview:profile   # Preview with profiling settings

# Development commands
```bash
pnpm run dev:all       # Start all services
pnpm run trigger       # Start Trigger.dev CLI

📁 Project Structure

🔐 Secrets & Environment

CI/CD (GitHub Actions) - Recommended

For automatic deployments, use GitHub Environments with secrets:

Set up GitHub Environments: Create dev and prod environments (Settings → Environments)
Add secrets to each environment (same secret names, different values per environment)
Secrets are automatically available in GitHub Actions workflows

Separate Workers: Development and production use separate Cloudflare Workers for complete isolation.

Manual Secret Management (Local)

Note: GitHub Actions automatically manages secrets during CI/CD. Manual secret management is mainly for local testing.

For manual secret setup from your local machine:

# 1. Create .env.secrets.dev and .env.secrets.prod files (gitignored)
# Format: KEY=value (one per line)
# .env.secrets.dev: Sandbox QuickBooks + other dev secrets
# .env.secrets.prod: Production QuickBooks + other prod secrets

# 2. Upload to Cloudflare Worker (sets secrets in respective environment workers)
```bash
pnpm run secrets:dev    # Upload secrets to dev worker
pnpm run secrets:prod   # Upload secrets to prod worker

Security Notes

Never commit .env.secrets.* (they're gitignored)
GitHub Environments are the recommended way for CI/CD (secrets isolated per environment)
Secrets are encrypted and managed via wrangler secret put or GitHub Environments
Use .dev.vars only for non-sensitive local config
Environment variables are defined in wrangler.jsonc per environment
Environment isolation: Separate workers for dev/prod with isolated secrets

📁 Project Structure

├── app/                 # Next.js App Router pages
├── components/          # React components
├── content/            # MDX blog content
├── lib/                # Utilities & integrations
├── public/             # Static assets
├── scripts/            # Build & utility scripts
```text
├── trigger/            # Background job definitions
└── wrangler.jsonc      # Cloudflare Workers config

🛠️ Development Scripts

# Development
pnpm run dev:all        # Full stack (Next.js + Wrangler + Trigger)
pnpm run dev            # Next.js development server
pnpm run dev:turbo      # Next.js with TurboPack (faster)
pnpm run wrangler       # Cloudflare Workers dev server
pnpm run trigger        # Trigger.dev background jobs

# Building
pnpm run build:all             # Build Next.js + OpenNext
pnpm run build                 # Next.js build only
pnpm run build:opennext        # Cloudflare OpenNext build
pnpm run build:opennext:profile # Build with profiling (unminified)

# Testing
pnpm run preview        # Test built Cloudflare app locally
pnpm run check          # Run all code quality checks
pnpm run lint           # ESLint
pnpm run format         # Prettier
pnpm run check:ts       # TypeScript check

# Deployment
pnpm run deploy:dev     # Deploy to development
pnpm run deploy:prod    # Deploy to production
pnpm run deploy         # Quick production deploy

# Version Management
pnpm run version:upload # Upload version to production
pnpm run version:list   # List all versions
pnpm run version:deploy # Deploy latest version

# Secrets
pnpm run secrets:dev    # Upload dev secrets to dev worker (.github/scripts/secrets.sh)
pnpm run secrets:prod   # Upload prod secrets to prod worker (.github/scripts/secrets.sh)

# Infrastructure
pnpm run setup:bindings # Setup Cloudflare bindings (R2, KV)
```bash
pnpm run cf:typegen     # Generate Cloudflare types
pnpm run analyze:bundle # Bundle size analysis guidance
pnpm run coc:generate   # Generate Code of Conduct

Troubleshooting

See PNPM_SCRIPTS.md for detailed script explanations.

🐛 Troubleshooting

Common Issues

Build fails with "Module not found"

# Clear caches and reinstall
```bash
rm -rf node_modules .next .open-next
pnpm install

Wrangler secrets not working

# Check secrets are uploaded (for dev environment)
npx wrangler secret list --env dev

# For production environment
npx wrangler secret list --env prod

# Re-upload if needed
# Local secrets are handled via .dev.vars

Trigger.dev not connecting

```bash
# Check Trigger.dev CLI is running
pnpm run trigger

Environment variables not loading

Check .dev.vars syntax (KEY=value, one per line)
Ensure NODE_ENV is set correctly (Next.js sets this automatically - use only development, production, or test)
Restart development servers after changes

Performance Profiling

For performance analysis and debugging:

# Build with profiling (unminified code for easier debugging)
pnpm run build:opennext:profile

# Preview with profiling settings
pnpm run preview:profile

# Analyze bundle size after building
pnpm run analyze:bundle
# After running, check .open-next/server-functions/default/handler.mjs.meta.json
# Upload to https://esbuild.github.io/analyze/ for detailed bundle analysis

Need Help?

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Check PNPM_SCRIPTS.md for detailed script info

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes and test locally
Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

Built with ❤️ by the All Things Linux community.

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

All Things Linux

🚀 Quick Start

📋 Tech Stack

📋 Prerequisites

🛠️ Setup & Development

1. Clone & Install

2. Setup Cloudflare Bindings

3. Configure Secrets

4. Start Development

🚀 Deployment

Automatic Deployments (GitHub Actions CI/CD)

Manual Deployments

Quick Deploy (Immediate)

Version Management (Safer Production)

Build Process

📁 Project Structure

🔐 Secrets & Environment

CI/CD (GitHub Actions) - Recommended

Manual Secret Management (Local)

Security Notes

📁 Project Structure

🛠️ Development Scripts

Troubleshooting

🐛 Troubleshooting

Common Issues

Build fails with "Module not found"

Wrangler secrets not working

Trigger.dev not connecting

Environment variables not loading

Performance Profiling

Need Help?

🤝 Contributing

About

Resources

Code of conduct

Stars

Watchers

Forks

Used by

Contributors

Languages