Deployment #

Requirements #

Docker with the compose plugin.
A domain with HTTPS.
A reverse proxy for TLS.
The lexicons and permission set published.

Setup #

Clone the repository on the server.
Copy .env.example to .env. Generate the secrets with docker compose run --rm scn-chat pnpm keys, and set at least:
- SECRET_KEY and OAUTH_PRIVATE_KEYS, from pnpm keys.
- PUBLIC_URL to the HTTPS URL, such as https://chat.example.com.
- ADMIN_DIDS to your admin DID(s), comma separated.
- NODE_ENV to production.
Leave OAUTH_SCOPE_MODE unset, so it defaults to permission-set. raw is only for testing the local fallback before the lexicons are published, and production refuses it.
Start it with docker compose up -d --build. For development, run pnpm dev, or pnpm preview to try the production build on your own machine.
Point the reverse proxy at http://127.0.0.1:3000, if applicable. A deployment's port never moves, so the server fails to start if the port is taken.
Sign in and open the admin area, from Settings > Admin. Configure your plugins and models. Note that a model provider plugin will need to be enabled before models can be configured.

Set up cron. Issue a key with the admin role under Admin > API keys. Then setup cron as so:

*/5 * * * * curl -fsS -X POST -H "Authorization: Bearer <key>" https://chat.example.com/api/cron

Config import/export #

All admin settings can be exported and imported via the CLI.

Export the configuration:
```
docker compose exec -T scn-chat node apps/server/src/site-config-cli.ts export > site-config.json
```
The JSON file contains all admin settings, roles, plugins, and admin models. Secrets are not exported.
Import the config:
```
docker compose exec -T scn-chat node apps/server/src/site-config-cli.ts apply < site-config.json
```
Changes take effect without a restart. If the import includes setting changes that will prevent the server from starting, the script will bail. Broken plugin settings that don't affect startup will still be imported with a warning.

Applying the config is a full reset so any admin config that wasn't in the initial export will be cleared.

Secrets missing from the file are ignored / left unchanged on the server. To clear a secret, set it to null, such as "secrets": { "tavilyApiKey": null }.
A role in the JSON that leaves members unset will keep its members.
Plugin packages need to be added to package.json to be available in the site.

For Ansible, template the file from your variables and Vault and apply it:

- name: Apply the SCN Chat configuration
  ansible.builtin.shell: >
    docker compose exec -T scn-chat node apps/server/src/site-config-cli.ts apply < site-config.json
  args:
    chdir: /srv/scn-chat
  register: site_config
  changed_when: site_config.stdout != 'No changes.'