Automated Deployment

TIP

Prefer to do things manually, or want to understand the steps involved? Checkout the this guide

TL'DR

Fork, clone, cd, install, add env vars (API key and domain), then run make deploy

Overview

The deployment process provisions ~20 Cloudflare resources and deploys your application in a single command:

graph LR
    subgraph Setup
        A[Install Tools] --> B[Fork & Clone]
        B --> C[Configure .env]
    end

    subgraph Deployment["make deploy"]
        D[Preflight Checks] --> E[Terraform Apply]
        E --> F[Generate Config]
        F --> G[Install & Build]
        G --> H[DB Migrations]
        H --> I[Deploy Workers]
        I --> J[Deploy Frontend]
        J --> K[Set Secrets]
        K --> L[Smoke Tests]
    end

    C --> D
    L --> M{Success?}
    M -->|Yes| N[Live!]
    M -->|No| O[Check Logs]

    style N fill:#22c55e
    style O fill:#ef4444
    style D fill:#3b82f6
    style E fill:#3b82f6

Prerequisites

Install these tools before starting:

Tool	Version	Purpose	Install
Git	Any	Clone repository	git-scm.com
Node.js	20+	JavaScript runtime	nodejs.org
pnpm	8+	Package manager	npm install -g pnpm
Terraform	1.5+	Infrastructure as code	terraform.io
Wrangler	Latest	Cloudflare CLI	npm install -g wrangler
Make	Any	Run deployment scripts	Usually pre-installed

You'll also need:

• Cloudflare account (free tier works)
• Domain name added to Cloudflare
• GitHub account (for authentication)
• 30 minutes of time

Step 1: Fork & Clone

Fork the repository to your GitHub account, then clone it:

# Fork on GitHub first: https://github.com/lissy93/pixelflare/fork

# Clone your fork
git clone https://github.com/YOUR-USERNAME/pixelflare.git
cd pixelflare

# Install dependencies
pnpm install

TIP

Forking lets you track your changes, push updates, and optionally set up CI/CD with GitHub Actions.

Step 2: Cloudflare Setup

Create API Token

1. Go to Cloudflare → Profile (top-right) → API Tokens
2. Click Create Token, and give it an imaginative name
3. Complete the token, with the following permissions:

Scope	Resource	Access
Account	AI Gateway	Edit
Account	Workers AI	Edit
Account	D1	Edit
Account	Cloudflare Pages	Edit
Account	Workers R2 Storage	Edit
Account	Cloudflare Images	Edit
Account	Account Analytics	Read
Account	Workers KV Storage	Edit
Account	Workers Scripts	Edit
Account	Stream	Edit
Account	Access: Apps and Policies	Edit
Zone	Single Redirect	Edit
Zone	Zone WAF	Edit
Zone	Workers Routes	Edit
Zone	SSL and Certificates	Edit
Zone	Logs	Read
Zone	Page Rules	Edit
Zone	Firewall Services	Edit
Zone	DNS	Edit

• Account Resources
  • Include account: [your-account-id]
  • Token is restricted to this specific Cloudflare account
• Zone Resources
  • Include a specific zone
  • Zone: [your-domain.com]
  • Token can only operate on this DNS zone
• Client IP Address Filtering
  • Not configured
  • Token can be used from any IP address
  • Optional restriction to specific IPs or CIDR ranges
• TTL (Time To Live)
  • Not set
  • Token does not expire automatically
  • Optional start and end dates can limit token lifetime

By the end, your screen should look similar to this:

Get Account ID

1. Go to Cloudflare Dashboard
2. Click any domain
3. Scroll down in the right sidebar - copy your Account ID

Example Account ID location

Step 3: Configure Environment

Create your environment file:

cp .env.example .env

Edit .env and set these three required variables:

# Essential Configuration
CLOUDFLARE_ACCOUNT_ID='abc123def456...'   # From step 2
CLOUDFLARE_API_TOKEN='your-api-token'     # From step 2
DOMAIN='yourdomain.com'                   # Your domain (needs to be Cloudflare)

That's it! Everything else has sensible defaults or is auto-generated.

NOTE

Optional: Set ACCESS_TEAM_DOMAIN='your-team-name' to customize your Cloudflare Access subdomain (e.g., your-team.cloudflareaccess.com).

Optional Configuration

See the configuration guides for details on configuring other features.

Step 4: Deploy

Run the deployment script:

make deploy

This will:

1. ✓ Preflight checks - Verify tools, credentials, domain
2. ✓ Terraform apply - Create all Cloudflare resources
3. ✓ Generate configs - Create wrangler.toml from Terraform outputs
4. ✓ Install & build - Compile TypeScript, bundle assets
5. ✓ Database migrations - Set up D1 schema
6. ✓ Deploy Workers - Upload API and gateway workers
7. ✓ Deploy frontend - Build and deploy SvelteKit app to Pages
8. ✓ Set secrets - Upload API keys and generated secrets
9. ✓ Smoke tests - Verify deployment is working

Deployment typically takes 5-10 minutes on first run.

IMPORTANT

Secrets are auto-generated by Terraform if not provided. You don't need to manually create API_HASH_SECRET, UPLOAD_TOKEN_SECRET, etc. - they're generated securely and set automatically.

What Gets Created

Your deployment provisions:

Storage:

• R2 bucket (pixflare-production-images)
• D1 database (pixflare-production-db)
• KV namespace (pixflare-production-cache)
• 3 Queues (variant processing, backups, custom domains)

Workers:

• API Worker (Hono-based REST API)
• Gateway Worker (optional, single-domain routing)

Frontend:

• Cloudflare Pages project
• Custom domain DNS records

Authentication:

• Cloudflare Access application (optional)
• GitHub OAuth identity provider

Optional:

• Vectorize index (AI embeddings)
• Analytics Engine dataset
• WAF rules (R2 protection)

Step 5: Verify

Once deployment completes, some smoke tests will run and check that everything is up and running like it should.

You can also test this yourself, for example:

• Frontend: https://yourdomain.com
• API Health: https://yourdomain.com/api/v1/health
• API Docs: https://yourdomain.com/api/v1/docs

You should now be able to login and get started!

1. Visit your frontend URL
2. Click Sign In
3. Authenticate with GitHub via Cloudflare Access
4. Start uploading cat pics!

Troubleshooting

Having issues? See the Troubleshooting Guide for common problems and solutions.

Quick checks:

• Verify .env has correct CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and DOMAIN
• Ensure API token has all required permissions
• Check domain is active in Cloudflare
• Run make help to see all available commands

Deployment Options

See the Makefile for more all commands.

Updating Pixelflare

To update your deployment, re-pull the latest code, update dependencies, and re-deploy. Or:

make update
make deploy

Terraform will only update changed resources.

Next Steps

Your Pixelflare instance is live! But there's more features you can enable and configure, with simple toggles and env vars. Explore these in the Config docs 😃

No pages found in this section.