forgejo-fly/README.md

Forgejo on Fly.io

Standalone Forgejo deployment for Fly.io with one initial admin, optional Caddy HTTP basic auth, and optional restic backups.

Setup

Install and authenticate the Fly CLI, then run:

./setup.sh

The script prompts for:

• A globally unique Fly app name
• A Fly region
• The initial Forgejo admin username and email
• Whether visitors must sign in before viewing Forgejo
• Whether to enable Caddy HTTP basic auth and, if enabled, its single username and password

It creates the Fly app, writes the generated fly.toml, stores credentials as Fly secrets, and deploys Forgejo with a 10 GB persistent volume. The Forgejo admin password is generated securely and printed before and after deployment. Save it when displayed.

The app is available at https://<appname>.fly.dev/. Registration is disabled, so the generated admin is the only account on a new installation. Add any later users through Forgejo's admin interface.

Access Control

Two independent settings restrict access by default:

• Forgejo's GITEA__service__REQUIRE_SIGNIN_VIEW prevents anonymous visitors from viewing Forgejo content when enabled during setup.
• Caddy basic auth is enabled when both CADDY_BASIC_AUTH_USERNAME and CADDY_BASIC_AUTH_PASSWORD are set. The setup script can configure them for you. Git HTTP endpoints and the package API remain outside Caddy authentication so Git and package clients can authenticate directly with Forgejo.

To make the instance publicly viewable, answer no to both access-control prompts during setup. For an existing instance, leave the Caddy credentials unset, change GITEA__service__REQUIRE_SIGNIN_VIEW to false in the generated fly.toml, then run fly deploy.

To enable or change Caddy authentication later:

fly secrets set CADDY_BASIC_AUTH_USERNAME=forge CADDY_BASIC_AUTH_PASSWORD='your-password'

To disable it, unset both secrets:

fly secrets unset CADDY_BASIC_AUTH_USERNAME CADDY_BASIC_AUTH_PASSWORD

Backups

Set all restic configuration as Fly secrets. Backups stay disabled until every value is present.

fly secrets set \
  AWS_ACCESS_KEY_ID='...' \
  AWS_SECRET_ACCESS_KEY='...' \
  RESTIC_REPOSITORY='s3:https://.../forgejo' \
  RESTIC_PASSWORD='...'

Initialize the repository once:

fly ssh console --command "/usr/local/bin/backup-init.sh"

The backup process snapshots /data hourly when all required variables are available. To restore a snapshot from inside a stopped or debug machine:

backup-restore.sh latest

Debug Startup

Set DEBUGDEPLOY to keep a machine alive without starting services, or use:

./bin/debug-deploy.sh start
./bin/debug-deploy.sh stop