Chartbrew Docs

This guide sets up a new installation with a published Chartbrew image, PostgreSQL, and Redis. It requires Docker Engine with the Compose plugin. See Docker installation for your operating system. For an existing installation, keep its database, volumes, and encryption key. Follow the migration guide when upgrading from v5.

1. Create the configuration

Create a directory for your deployment and a .env file inside it. Select an exact image tag from the Chartbrew image repository.

CHARTBREW_IMAGE=razvanilin/chartbrew:YOUR_RELEASE_TAG
CB_DB_NAME=chartbrew
CB_DB_USERNAME=chartbrew
CB_DB_PASSWORD=REPLACE_WITH_A_RANDOM_PASSWORD
CB_ENCRYPTION_KEY=REPLACE_WITH_A_64_CHARACTER_HEX_KEY
CB_SECRET=REPLACE_WITH_A_SEPARATE_RANDOM_SECRET
CB_BULLMQ_USERNAME=chartbrew
CB_BULLMQ_PASSWORD=REPLACE_WITH_A_RANDOM_PASSWORD
VITE_APP_CLIENT_HOST=https://charts.example.com
VITE_APP_API_HOST=https://charts-api.example.com

CHARTBREW_IMAGE is used by this Compose example to select the image. Replace every placeholder before you start. Generate an encryption key with openssl rand -hex 32. Run it again for each separate password or secret. Save these values securely and keep them during upgrades. The public URLs must be reachable from your browser. For a local-only test, use http://localhost:4018 and http://localhost:4019. For a server, configure Domains and HTTPS.

chmod 600 .env

2. Add the Compose file

Save this as compose.yaml beside .env:

services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${CB_DB_NAME}
      POSTGRES_USER: ${CB_DB_USERNAME}
      POSTGRES_PASSWORD: ${CB_DB_PASSWORD}
    volumes:
      - database:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${CB_DB_USERNAME} -d ${CB_DB_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis:/data

  chartbrew:
    image: ${CHARTBREW_IMAGE}
    restart: unless-stopped
    env_file: .env
    environment:
      CB_API_HOST: 0.0.0.0
      CB_API_PORT: 4019
      CB_DB_HOST: db
      CB_DB_PORT: 5432
      CB_DB_DIALECT: postgres
      CB_REDIS_HOST: redis
      CB_REDIS_PORT: 6379
      CB_REDIS_PASSWORD: ""
      VITE_APP_CLIENT_PORT: 4018
    ports:
      - "127.0.0.1:4018:4018"
      - "127.0.0.1:4019:4019"
    volumes:
      - uploads:/code/server/uploads
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

volumes:
  database:
  redis:
  uploads:

The database and Redis are only available inside the Compose network. Redis has no password in this example, so do not publish its port. The client and API ports bind to the host’s loopback address for a reverse proxy on that host. If your proxy runs in another container, connect it to the same Docker network and use chartbrew:4018 and chartbrew:4019 as upstream addresses.

3. Start Chartbrew

From the deployment directory:

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs --tail=100 chartbrew

Wait for database migrations and the client build to complete. A running container alone does not confirm that the API and client are ready. Open the configured client URL and complete the deployment checks. You can also check the image renderer:

docker compose exec -w /code/server chartbrew npm run image:smoke

Change configuration

After editing .env, recreate the application container:

docker compose up -d --force-recreate chartbrew

The image’s entrypoint rebuilds the client at startup with the supplied VITE_APP_* values. Wait for the build to finish, then reload the page. A restart alone does not apply changed Compose environment values. Add SMTP or integration settings to .env as needed. See Environment variables. Never put server secrets in VITE_APP_* variables because the browser receives them.

Other database and build options

Chartbrew supports MySQL and PostgreSQL. To use an existing database, remove the db service and its depends_on entry, then set the database host, port, credentials, and dialect to match it. Use mysql for MySQL or postgres for PostgreSQL. To build from source, the repository includes MySQL and PostgreSQL examples. Select your release first, keep the complete checkout, and configure .env. Inside Docker, localhost refers to the current container; use service names such as db and redis for the bundled services. Before using those repository examples on a public server, remove the Redis port mapping, add persistent upload storage, and restrict the application ports as shown above. Setting REDIS_PASSWORD in the official Redis image’s environment does not itself enable Redis authentication. Configure Redis authentication explicitly if your network requires it.

Back up and upgrade

Back up the database with database-native tools, the uploads volume, and .env. Test your restore procedure. Do not run docker compose down -v unless you intend to delete the data volumes. For upgrades, stop the application, make a backup, select the new image tag, and follow the release’s migration instructions. Keep the database image version unchanged during an application upgrade unless you also plan a database upgrade.

Get Started

Deployment

Integrations

Charts

Architecture

Migrations

Run with Docker

1. Create the configuration

2. Add the Compose file

3. Start Chartbrew

Change configuration

Other database and build options

Back up and upgrade

​1. Create the configuration

​2. Add the Compose file

​3. Start Chartbrew

​Change configuration

​Other database and build options

​Back up and upgrade

1. Create the configuration

2. Add the Compose file

3. Start Chartbrew

Change configuration

Other database and build options

Back up and upgrade