Skip to main content

Installation & Deployment Runbook

End-to-end steps to stand up the Ticku platform — a single shared, multi-tenant deployment that hosts all customer tenants. You deploy this once; individual customer organizations are then added as tenants without redeploying — see Tenant Provisioning.

Prerequisites​

  • A server (or container host) with Docker and Docker Compose
  • A PostgreSQL database (containerized or managed, e.g. Neon/Azure Database), sized for all tenants combined
  • A public HTTPS domain for the app (required for Teams and Graph webhooks)
  • Azure AD (Entra ID) admin access — for the platform SSO app registration and Teams deployment
  • An Azure Storage account — for file attachments

Deployment Steps​

1. Azure App Registration (platform SSO)​

Follow Azure App Registration to create the platform SSO app. You will collect: tenant ID, client ID, client secret. Add the Mail.ReadWrite / Mail.Send application permissions at the same time if any tenant will use app-only email-to-ticket — see Connection Modes.

2. Configure Environment​

Copy .env.production.example to .env.production and fill in every value. Full reference: Environment Variables.

cp .env.production.example .env.production
# generate secrets:
openssl rand -hex 32   # BETTER_AUTH_SECRET
openssl rand -hex 32   # EMAIL_ENCRYPTION_KEY

3. Build & Start​

See Docker for the full compose stack.

docker compose up -d --build

4. Migrate & Seed the Database​

npm run db:migrate   # apply schema (migrate deploy — never db push on real data)
npm run db:seed      # seed baseline data

See Database for details and backup guidance.

4a. Bootstrap the first platform admin​

Visit /setup on the fresh deployment to create the first platform admin. This page refuses to run once any user exists, so do it before anyone signs in. The platform admin then creates the first tenant — see Tenant Provisioning and Tenants & Platform Admin.

5. Deploy the Teams App​

Fill in manifest/manifest.json (app ID, client ID, your domain), add the two icons, zip the package, and upload via Teams Admin Center. Full steps: Teams Setup.

6. Verify​

  • Open https://<your-domain> — the web login page loads
  • Sign in via Microsoft SSO — lands on the workspace dashboard
  • Open the Ticku tab in Teams — silent SSO works, no login prompt
  • Create a test ticket, assign it, confirm the notification arrives

Post-Deployment​

  • Create the first tenant(s) — see Tenant Provisioning
  • Hand each tenant's first admin the Admin Day-1 Checklist
  • Record the platform SSO client-secret expiry and schedule rotation
  • Set up database backups (see Database)
  • Ensure scheduled jobs run (SLA checks, reminder firing, Graph subscription renewal)