Setting up a project for Fargone

Everything you need to prepare a codebase for deployment, use the CDN, and develop locally against the real platform.

Preparing for nixpacks

Fargone builds with nixpacks — it inspects your project and picks a runtime automatically. Most projects need zero configuration, but a few things help:

What nixpacks detects

Node.js — package.json present (picks npm, pnpm or yarn by lock file)
Python — requirements.txt or pyproject.toml
Go — go.mod
Rust — Cargo.toml
Ruby — Gemfile
PHP — composer.json
Deno / Bun — deno.json / bun.lockb
Static sites — index.html at root

Checklist

Lock file committed. nixpacks uses it to install. If you use pnpm, commit pnpm-lock.yaml; for yarn, commit yarn.lock.
start script in package.json. Nixpacks runs npm start by default. If your entry point is something else (e.g. node server.js), either set a start script or add a nixpacks.json:
```
{
  "start": { "cmd": "node server.js" }
}
```
No Dockerfile needed. nixpacks produces the Docker image. If you have a Dockerfile it will be ignored.
Build commands. nixpacks runs npm ci (or equivalent) automatically. If you need a pre-build step (e.g. prisma generate), add it to a nixpacks.json:
```
{
  "build": { "commands": ["prisma generate"] }
}
```
Port. Containers listen on port 3000 by default. Set the internal port in the dashboard if your app uses a different one.

Environment variables

Set env vars in the dashboard (Settings → Env) or via the CLI:

fargone env set my-app DATABASE_URL=postgres://… NODE_ENV=production

Env vars are injected into the container on the next deploy — redeploy after changing them.

Using the CDN

The CDN gives your app a namespace for static files. Upload from your code, serve them from the public URL.

How it works

Every deployed app gets four managed env vars injected automatically:

Variable	Purpose
`FARGONE_CDN_URL`	Upload endpoint (`POST` with `Authorization: Bearer` + `path` form field)
`FARGONE_CDN_PUBLIC_URL`	Public read base URL
`FARGONE_CDN_TOKEN`	Bearer token for uploads
`FARGONE_CDN_PREFIX`	Your app's namespace

Upload a file (Node.js)

const res = await fetch(process.env.FARGONE_CDN_URL, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FARGONE_CDN_TOKEN}` },
  body: (() => {
    const fd = new FormData();
    fd.append("path", "images/photo.jpg");
    fd.append("file", new Blob([buffer], { type: "image/jpeg" }), "photo.jpg");
    return fd;
  })(),
});

const { url } = await res.json();
// url = "https://fargone.sh/cdn/my-app/images/photo.jpg"

Upload a file (curl)

curl -X POST "$FARGONE_CDN_URL" \
  -H "Authorization: Bearer $FARGONE_CDN_TOKEN" \
  -F "path=images/photo.jpg" \
  -F "file=@photo.jpg"

Serve it

The file is immediately available at FARGONE_CDN_PUBLIC_URL/<path>:

https://fargone.sh/cdn/my-app/images/photo.jpg

Files are served with a long cache lifetime. Anyone with the link can fetch them — treat CDN URLs as public.

Rotate tokens

If a token is compromised, rotate it:

fargone cdn rotate my-app

This kills the old token instantly. Redeploy the app so its container picks up the new one.

Local development

Mocking the app locally

When running npm run dev locally, you want your app to behave the same as on the platform. Here's the full setup:

1. Enable the local proxy

The built-in reverse proxy makes your app reachable as my-app.localhost:<port>, matching the platform URL pattern:

# .env
FARGONE_LOCAL_PROXY=true
FARGONE_PROXY_PORT=8080
FARGONE_DOMAIN=localhost

Start the worker with npm run worker — it runs the proxy alongside the build and deploy machinery.

2. Mirror CDN env vars

Pull the real CDN vars for your app:

fargone cdn env my-app

This prints an export block. Paste it into your local .env or shell. Now your local app uses the same CDN namespace and token as production.

3. Mirror database URLs

If your app uses a managed database, the connection string is already in the app's env on the platform. Pull it:

fargone env my-app | grep DATABASE_URL

Set it locally — your dev server connects to the same database the deployed container uses (or use a local Postgres for faster iteration).

4. Run the dev server

npm run dev

Your app is on http://localhost:3000. If the proxy is on, it's also on http://my-app.localhost:8080.

Summary: local `.env` template

# Platform
DATABASE_URL=postgresql://fargone:fargone@localhost:5432/fargone
FARGONE_APP_URL=http://localhost:3000
FARGONE_DOMAIN=localhost
FARGONE_LOCAL_PROXY=true
FARGONE_PROXY_PORT=8080

# CDN (from `fargone cdn env my-app`)
FARGONE_CDN_URL=https://fargone.sh/api/cdn
FARGONE_CDN_PUBLIC_URL=https://fargone.sh/cdn/my-app
FARGONE_CDN_TOKEN=fgcdn_…
FARGONE_CDN_PREFIX=my-app

# Your app's env
NODE_ENV=development

Next steps

Quickstart — deploy your first app
CDN — full CDN docs
Databases — attach Postgres, Redis, MariaDB or MongoDB
CLI — manage everything from the terminal
Node.js library — use the API from your own code