PacketChatDocs

Deploy PacketChat#

The supported self-hosted path uses Docker Compose to run the web application, worker, PostgreSQL, Redis, MinIO, and one-time initialisation services.

The worker consumes four queues: file ingestion, provider synchronisation, asynchronous agent runs, and scheduled retention cleanup. Keep it running in every deployment that uses asynchronous agent runs; synchronous runs and chat continue to execute in the web process.

Before you start#

  • Install Docker with the Compose plugin.
  • Install Node.js 22 or newer and npm 10 or newer for the repository wrappers.
  • Obtain an authorised checkout of the private PacketChat source repository.
  • Reserve a durable host or managed volumes for database and object data.
  • Choose the public HTTPS URL before generating production configuration.

Prepare the environment#

  1. Enter the authorised repository checkout.

  2. Copy the environment template.

    cp .env.example .env

  3. Complete every required value using Configuration.

  4. Keep .env out of source control and deployment logs.

Start the stack#

  1. Build and start the long-running services.

    npm run compose:up

  2. Apply database migrations.

    npm run compose:migrate

  3. Check readiness on the published web port.

    curl -fsS http://localhost:3000/api/readyz

Use the npm wrappers because they consistently pass .env and the repository Compose file. A plain docker compose up from another directory may select a different environment or no file at all.

Put PacketChat behind HTTPS#

Proxy the single published web port. Forward the original scheme and client address only from a proxy you control. Set the public base URL, secure-cookie mode, and trusted-proxy option as described in Configuration.

Do not publish PostgreSQL, Redis, or MinIO administration ports to the public network. The web and worker containers reach those services on the Compose network.

Stop and restart#

Use the repository lifecycle scripts so the same Compose file and environment are selected:

npm run compose:logs
npm run compose:down
npm run compose:up

Apply migrations after updating the checkout and before returning traffic to a new application version.

Stopping the stack sends the worker a termination signal. The worker then drains for up to twenty seconds to finish or release the jobs it holds, inside the thirty-second grace period Compose allows before Docker stops the container. An agent run may hold the worker for up to fifteen minutes, so stop the stack deliberately rather than killing the container, and expect a long run that is still executing when the drain expires to end as timed_out rather than finished.

Warning: upgrading to this release removes duplicate model bindings. Where the same model was bound more than once to one provider account, only the most recently updated row survives, and it is left enabled if any of the collapsed rows was enabled. Review Admin → Providers after the migration and confirm the enabled model list matches what you intend to offer.

Verify#

  1. Run the readiness request and confirm database, Redis, and object storage are healthy. The three checks run together and each is bounded, so the response arrives within a few seconds and names the failing dependency even while that dependency is down.
  2. Inspect the Compose service list, including the completed migration service when the tools profile is shown.
  3. Open /login through the public HTTPS hostname.
  4. Continue with First run.

If it does not work#

Symptom Check
Compose reports missing variables Complete .env; production secrets have no usable default.
Readiness reports database failure Check PostgreSQL credentials, migration output, and volume permissions.
Readiness reports Redis failure Confirm Redis is running and its URL resolves inside the Compose network. While it is unreachable, rate limiting is skipped rather than blocking requests, each skipped check is logged at error level, and asynchronous agent runs fall back to the web process.
Readiness reports object-storage failure Confirm MinIO initialised every required bucket.
Login loops behind the proxy Confirm the public URL uses HTTPS and secure-cookie/proxy settings match the edge.