zcli-playground/gitea/README.md

Gitea on Zerops

Self-hosted Gitea backed by HA Postgres and SeaweedFS shared storage.

Prepare secrets

Gitea validates its security secrets at startup and tries to rewrite app.ini if they're missing or malformed. Zerops' <@generateRandomString> preprocessor produces alphanumeric values that don't match Gitea's required formats (base64url-32 bytes for JWT_SECRET / LFS_JWT_SECRET, a signed JWT for INTERNAL_TOKEN), so generate them with the Gitea binary itself:

./generate-secrets.sh

It downloads the matching Gitea release and prints four KEY=VALUE lines. Paste each value into the gitea service's secret env vars in the Zerops GUI (or pre-fill zerops-service-import.yaml before importing).

DB_PASSWORD is generated by the Zerops preprocessor (<@generateRandomString>) during import — cross-service expansion like ${db_password} is not evaluated inside the import.yaml, so the gitea service generates its own value and the Postgres service must be initialized with the same one.

Bootstrap

1. Paste zerops-service-import.yaml into the Zerops GUI: project → Import service → fill in the four secrets from step above.
2. Push the gitea config and build recipe:

   zcli push gitea
   

3. Create the admin user from the running container (service console):

   sudo -u git -E /usr/local/bin/gitea admin user create \
     --config /etc/gitea/app.ini \
     --admin \
     --username admin \
     --email you@example.com \
     --password 'choose-a-strong-one' \
     --must-change-password=false
   

4. Log in at the service's HTTPS URL and add your SSH public key under Settings → SSH/GPG Keys.

SSH access

Gitea's built-in SSH listens on port 2222 in the container. Zerops custom domains only carry HTTPS, so SSH needs one of:

• Public IPv4/IPv6 on the gitea service — Zerops GUI → service → Public Routing → add IP, open port 2222. Map :2222 → :2222.

After SSH works, set SSH_DOMAIN / ROOT_URL overrides if you use a custom hostname, otherwise Gitea will print clone URLs using the autogenerated Zerops subdomain.