Fircle landing pageFircle
Self-hosting docs

Fircle self-hosting setup guide

This walkthrough takes you from zero to a deployed Fircle instance with Cloudflare R2 for media, Supabase Postgres for data, generated web-push keys, and production-ready secrets. It is optimized for private, single-family deployments.

Jump To DeployEnvironment Template

Prerequisites

  • 1. A GitHub account with access to the repository.
  • 2. A Cloudflare account to create an R2 bucket and API keys.
  • 3. A Supabase account for a managed Postgres instance.
  • 4. A Vercel or Netlify account for deployment.
  • 5. A secure email you can reference in VAPID_SUBJECT (mailto:you@example.com).
Step 1

Configure Cloudflare R2 storage credentials

Click to expand

Open the detailed Cloudflare R2 setup guide

  1. 1. Open Cloudflare dashboard, then Storage and databases → R2 Object Storage → Overview.
  2. 2. Create a bucket (example: fircle-media).
  3. 3. In the Account Details panel, go to API Tokens and click Manage, then create an access key pair with bucket read/write permissions.
  4. 4. Save the Access Key ID and Secret Access Key securely. You will use them in deploy env vars.
  5. 5. Copy your Cloudflare Account ID from Account Details.
  6. 6. Configure or note the public bucket domain you want to use for object access.

Values to keep: R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, and R2_PUBLIC_BASE_URL.

Configure bucket CORS after deployment, when your final app domain is known. Use your deployed origin in AllowedOrigins and keep methods GET, PUT, HEAD with header content-type.

Step 2

Get your Supabase Postgres connection string

Click to expand

Open the detailed Supabase Postgres setup guide

  1. 1. Create a Supabase organization (first-time setup), then create your project.
  2. 2. Set and store your database password during project creation.
  3. 3. In the project dashboard, click Connect and choose ORM → Prisma.
  4. 4. Copy DATABASE_URL (pooled URI) and replace the password placeholder.
  5. 5. Copy DIRECT_URL (direct URI) from the same Prisma block.
  6. 6. Save both values in deploy environment variables before deploy.

Fircle expects both values: DATABASE_URL for pooled runtime access and DIRECT_URL for direct Prisma access.

Step 3

Generate VAPID keys for push notifications

Click to expand
  1. 1. Open vapidkeys.com.
  2. 2. Generate a new key pair.
  3. 3. Copy public key to NEXT_PUBLIC_VAPID_PUBLIC_KEY.
  4. 4. Copy private key to VAPID_PRIVATE_KEY.
  5. 5. Set VAPID_SUBJECT as mailto:your-email-address.

In production, Fircle expects all three VAPID variables together.

Step 4

Generate AUTH_SECRET

Click to expand
  1. 1. Open auth-secret-gen.vercel.app.
  2. 2. Generate a secure random secret string.
  3. 3. Store it as AUTH_SECRET in your deployment environment.
  4. 4. Do not commit this value to source control.
Step 5

Set environment variables

Click to expand

Use this starter template for Vercel or Netlify environment configuration.

DATABASE_URL="postgresql://postgres:[YOUR_PASSWORD]@[YOUR_HOST]:6543/postgres?pgbouncer=true&connection_limit=1&sslmode=require"
DIRECT_URL="postgresql://postgres:[YOUR_PASSWORD]@[YOUR_HOST]:5432/postgres"
AUTH_SECRET="[GENERATED_AUTH_SECRET]"
NODE_ENV="production"
STORAGE_DRIVER="r2"
SELF_HOSTED="true"

R2_ACCOUNT_ID="[CLOUDFLARE_ACCOUNT_ID]"
R2_BUCKET="[R2_BUCKET_NAME]"
R2_ACCESS_KEY_ID="[R2_ACCESS_KEY_ID]"
R2_SECRET_ACCESS_KEY="[R2_SECRET_ACCESS_KEY]"
R2_PUBLIC_BASE_URL="https://[PUBLIC_BUCKET_DOMAIN]"

NEXT_PUBLIC_VAPID_PUBLIC_KEY="[VAPID_PUBLIC_KEY]"
VAPID_PRIVATE_KEY="[VAPID_PRIVATE_KEY]"
VAPID_SUBJECT="mailto:[YOUR_EMAIL]"

Optional variables for advanced setups include domain verification tuning and ZeptoMail. For a first deployment, you can skip email variables.

Step 6

Deploy using one-click hosting flows

Click to expand

These buttons target the fircleco/fircle repository on main branch. You must fill real credentials and secrets before finishing deployment.

Deploy To VercelDeploy To Netlify

What to configure before pressing Deploy

  • 1. Confirm DATABASE_URL connects successfully from your host platform.
  • 2. Confirm R2 credentials have bucket-level read/write access.
  • 3. Confirm VAPID keys are copied exactly with no extra spaces.
  • 4. Confirm AUTH_SECRET is long, random, and only stored in env settings.
  • 5. Keep SELF_HOSTED=true for private single-family self-hosting.
Step 7

First boot and readiness checks

Click to expand
  1. 1. Open your deployed URL.
  2. 2. For fresh self-hosted instances, complete setup at /auth/setup.
  3. 3. If setup blocks, verify DB connectivity, R2 credentials, and VAPID values.
  4. 4. After setup, sign in and perform a smoke test: create a post, upload media, verify timeline.
  5. 5. Post-deployment: open your R2 bucket settings and set CORS policy to allow requests from your deployed domain.

Need lower-level operator docs?

See the repository self-hosting documentation for deeper operational guidance, migrations, and upgrade routines.

Open repository self-hosting guide