Migration guide — auth-mode=none → enabled

Apply migrations 008–014.

On the next start, nanosync auto-runs goose up. If you want to apply manually first to a maintenance window:

ns admin migrate up
# Or: goose -dir internal/db/migrations/postgres postgres "$DATABASE_URL" up

Verify the seeded tenant:

SELECT slug FROM orgs WHERE id = '00000000-0000-0000-0000-000000000001';
-- ('nanosync')

SELECT count(*) FROM projects WHERE id = '00000000-0000-0000-0000-000000000003';
-- (1)

Migration 013 backfilled every existing pipeline and connection with project_id = '00000000-0000-0000-0000-000000000003' (the default project). Confirm:

SELECT count(*) FROM pipelines WHERE project_id IS NULL;
-- (0)

Generate the master key.

openssl rand -hex 32 > /etc/nanosync/master.key
chmod 0600 /etc/nanosync/master.key
chown nanosync:nanosync /etc/nanosync/master.key

Back this up to your secrets vault. Losing it means losing every encrypted secret (SSO client secrets, SAML private keys). The key is NOT recoverable from the database — only from your backup.

Update the config.

auth:
  mode: enabled
  master_key_file: /etc/nanosync/master.key
  session_ttl: 12h

Don’t restart yet. The next step needs the daemon running in its current mode.

Bootstrap the first admin while still on --auth-mode=none.

This is the trick that makes the migration zero-downtime: you bootstrap before you flip the flag, while the server still answers as SystemRoot. The POST /v1/admin/bootstrap route is always available regardless of mode, and it creates the admin user + binds the admin role.

ns admin bootstrap \
  --email=admin@acme.com \
  --display-name='Acme Admin'
# Prompts for password interactively

Verify by logging in (still on --auth-mode=none, so this also succeeds):

ns auth login --email=admin@acme.com
ns auth whoami

Restart with --auth-mode=enabled.

systemctl restart nanosync

Confirm anonymous requests are now refused:

curl -sS -i http://localhost:8080/v1/pipelines
# HTTP/1.1 401 Unauthorized
# {"error":"unauthenticated"}

And confirm the admin still works:

ns auth login --email=admin@acme.com   # cookie now required by the server
ns pipeline list

Issue API tokens for any non-interactive callers.

Existing CI scripts and automation hitting the API now need to send a Bearer token:

ns token create --name=ci-deploys --ttl=8760h
# Output:
# ✓ token created — keep this secret, it will not be shown again
#   token: ns_a1b2c3d4_VeryLongRandomSecretGoesHereYouOnlySeeItOnce…
#   id:    01h…

Update your CI to send Authorization: Bearer ns_… on every API call.

Bind roles to additional users.

Now that admin works, invite the rest of your team and bind them to roles:

ns role bind editor --user=alice@acme.com \
  --scope=workspace --scope-id=<workspace-uuid>
ns role bind operator --user=oncall@acme.com \
  --scope=workspace --scope-id=<workspace-uuid>

See RBAC roles & bindings for the full role catalog and custom recipes.

(Optional) Wire SSO.

For larger teams, OIDC removes the password management burden. See SSO setup.