Create a superadministrator through the terminal for the first sign-in to the admin interface. You choose the username and password: there is no standard account or public owner-registration page.
Where application settings come from
For dev, settings come from .env: make dev prepares the file, and Makefile passes its values to processes. When running directly with go run, pass variables yourself — this does not read .env automatically.
For prod-local and servers, the controller reads deploy/environments/<имя>.json. It uses that file to create runtime configuration in <root>/config, place secrets in <root>/secrets, and mount files into containers. Changing the dev .env file does not change prod-local settings.
| Backend variable | Purpose |
|---|---|
APP_PROFILE |
local for dev, production for containerized server mode, including prod-local |
HTTP_HOST, HTTP_PORT |
API listening address and port; the reverse proxy exposes HTTPS |
DATABASE_URL / DATABASE_URL_FILE |
PostgreSQL connection string or path to a private file containing it |
DB_SSL_MODE |
Used in Makefile to build the dev DATABASE_URL; a complete DATABASE_URL takes priority |
MEDIA_ROOT |
Persistent local image directory accessible to the backend |
AUTH_SIGNING_KEYS_JSON_FILE |
Token signing keys file; the backend also accepts AUTH_SIGNING_KEYS_JSON |
AUTH_ACTIVE_SIGNING_KEY_ID |
Key used for new signatures |
AUTH_ISSUER |
Identifier of the token-issuing application |
ADMIN_ALLOWED_ORIGINS |
Allowed origins of the browser admin interface |
TRUSTED_PROXY_CIDRS |
Trusted reverse proxy networks |
In production, the backend connects to PostgreSQL with sslmode=verify-full. This verifies the certificate and server hostname; sslrootcert provides the trusted CA certificate path. The controller prepares these settings. If verification fails, fix the certificate or server address. Switching to disable or require removes the necessary check instead of fixing its cause.
An allowed origin determines where browser requests to the API may come from. The API checks permissions for specific entities and records separately. Never put tokens or keys in VITE_*: these variables are exposed to the frontend. Use rotation when changing server secrets so all components receive the new values.
In local dev
The first make dev prompts you to create an account. Initial superadmin already exists means an active superadministrator exists and this step was skipped. This is normal.
To run separately from the project root:
make up
make bootstrap-superadmin
In prod-local or on a server
After successful deployment, run the command on the computer or server where the backend runs:
docker exec -it example_project-local-backend-1 \
admin bootstrap-superadmin --if-needed --login owner
For a server, replace the container name with its actual name. Password input is hidden and requires confirmation. Requirements: 12–128 UTF-8 bytes, and the password must differ from the username. For ASCII, that is 12–128 characters; Cyrillic uses several bytes per character.
This command creates only the first superadministrator. It does not reset passwords or add another owner to existing accounts. --if-needed skips creation when initialization is complete. If accounts exist but none is an active superadministrator, access must be recovered separately. Do not delete database accounts to force bootstrap to run again.
Running without an interactive terminal
If the terminal cannot accept password input, pass --password-file /путь/к/файлу. This must be a regular file with 0600 permissions readable by the admin process. Do not pass the password as a command argument or environment variable. Do not commit the file to Git or print its contents in CI logs. When running in a container, make the file available to the backend process separately: a path on your computer is not automatically available inside the container.
Where access and domains are configured
| Setting | Purpose |
|---|---|
| Entity CRUD access | Operations available in the admin interface |
| External API access | Whether the external API is closed, requires sign-in, or allows anonymous access |
| External READ rules | Records the server allows through external list/get |
allowedOrigins in deployment JSON |
Exact origins allowed to send admin interface requests |
trustedProxyCIDRs |
Reverse proxies the backend trusts for client information |
| Signing keys and issuer | Application token signing and verification |
The first three settings are configured in Generator UI, then require Generate and an application update. Domain, origin, proxy, and secrets belong to the runtime environment. An origin includes protocol and a nonstandard port, if any: https://admin.local.test:8443.
In generated deployment, admin and API domains must follow the supported same-site arrangement — belong to the same site from the browser's perspective. Use HTTPS and exact origins in production. When sign-in fails, check these settings; do not disable origin/CSRF checks or trust every proxy.
After transferring a database
Accounts and password hashes are included in the dump. After importing the dev database into prod-local, sign in with the dev username and password, rather than the original prod-local account. A dump does not replace signing keys or other runtime secrets. Existing browser sessions may become invalid — sign out and sign in again.
If sign-in succeeds but subsequent requests are rejected, check the API address, HTTPS, allowedOrigins, server time, and browser cookies. If the backend itself does not start, begin with its logs: creating an account does not fix database or media-storage connectivity.
bash ./deploy/control logs --env local --service backend
For production, replace local with the environment name. Do not publish secret file contents together with logs.