Instance Initialisation

The API now initialises itself on first startup. It uses registered migrations, saves a generated JWT key and creates a random-password administrator when no user records exist. Read DATABASE_PATH/initial-admin.json for the initial login; with central Compose this is .tcgsd/database/initial-admin.json. These instructions describe the current source build; they do not imply that the changes are in a published image.

Automatic or manual setup

For automatic source setup, run npm ci, npm run build, then npm start. No .env is required. The API defaults to port 15100. For Docker, follow the container installation guide.

To choose credentials yourself before starting, use the manual steps below. Set AUTO_SETUP=false in the API’s optional .env to require manual migrations and account creation on future starts.

From app-tcg-set-designer-api, use Node 24.12 or newer in the 24 LTS line:

npm ci
npm run dev:setup
npm run build
npm run db:setup

Review the generated .env. Keep JWT_SECRET_KEY private and stable. DATABASE_PATH is the directory containing database.sqlite; templates and webhook files use their own configured directories. The generated API port is 15100.

Create a private UTF-8 password file outside the repository, then create your administrator:

npm run admin:create -- --username operator --email operator@example.com --password-file /absolute/path/password.txt
npm start

Use your own username and email. Choose a password between 12 and 1,024 characters, then remove the password file after successful setup. There is no shared default password. Visit http://localhost:15100/health to check that the API is running.

Connect the web client

In app-tcg-set-designer-web, run npm ci followed by npm run dev. Open the displayed Vite URL. Set API address to http://localhost:15100, then sign in with the account you created.

Install a server-managed template and follow the design workflow to create a set and save its first card. Saved content belongs to the API database; keep its directory when replacing application files.

Existing installations and recovery

Stop the API before running db:setup for an upgrade. Schema synchronisation has been replaced with migrations, and an existing database receives a checked backup before migration. Existing role grants are preserved and need review when permission columns are added.

The persistent installation guide covers backup/restore, old demo accounts, password reset, signing-key rotation, and recovery after a process crash. Do not run the development fixture command against a persistent installation.