Skip to content
Forge Docs

Browser Onboarding

Onboarding connects the running control plane to the domains and source control it needs for daily use.

Choose the Owner

Section titled “Choose the Owner”

Create the first owner account in the browser. This account controls system settings, deployment configuration, GitHub connection details, and maintenance panels.

Keep the owner account separate from any app users. It can change server-wide routing, backup, migration, and update settings.

Set the Control Plane Domain

Section titled “Set the Control Plane Domain”

You can serve Forge itself through Caddy by choosing a dashboard domain such as:

app.forgecloud.cc

Point the hostname at the server:

A     app.forgecloud.cc     YOUR_SERVER_IPV4
AAAA  app.forgecloud.cc     YOUR_SERVER_IPV6

Forge keeps the raw http://IP:4310 URL available as a fallback.

Configure GitHub

Section titled “Configure GitHub”

Forge works best with a GitHub App. Create one with these repository permissions:

  • Contents: Read
  • Metadata: Read

Subscribe it to the Push webhook event and point the webhook URL at:

https://YOUR_PUBLIC_HOST/api/github/app/webhook

Enter the app details during onboarding or later in system settings.

If you do not want to use a GitHub App, Forge can also read a GITHUB_ACCESS_TOKEN from the server environment. The GitHub App path is better for repository selection and push webhooks.

Add the Wildcard Root Domain

Section titled “Add the Wildcard Root Domain”

Set a wildcard root domain when you want Forge to generate service hostnames automatically:

*.apps.forgecloud.cc

With that root, a service named api can receive a generated hostname like:

api.apps.forgecloud.cc

You can still add public custom domains to individual services. The wildcard root just gives every eligible web service and database service a predictable generated hostname.

Connect Backup Storage

Section titled “Connect Backup Storage”

Automatic backups are off by default. In the Backups step, enable daily, weekly, or monthly schedules individually when new database services should create backups automatically. You can change these schedules later per database service from its Backups tab.

If you have a Cloudflare R2 bucket or token ready, connect R2 in the same step. Forge can then save database backups to disk, R2, or both.

The default backup destination is:

  • disk when R2 is not connected.
  • disk+r2 when R2 is connected.

You can change the destination per database service later.

Import a Forge Bundle

Section titled “Import a Forge Bundle”

If you are moving from another Forge server, use the migration import option during onboarding. Choose the .forge bundle file and enter the passphrase from the source server.

The import restores projects, services, users, domains, environment variables, static output, backup records, backup files, database dumps, Caddy config, and system settings. Forge clears auth sessions after import, then sends you through the success path so the restored owner account can sign in cleanly.

After Onboarding

Section titled “After Onboarding”

Once onboarding is complete, you can:

Restart Onboarding

Section titled “Restart Onboarding”

After the first run, System Settings includes a Restart onboarding action. Use it when you need to walk through domain, GitHub, R2, or migration setup again without reinstalling the server.