Campfire Documentation

Campfire is a web-based chat application that includes the following features:

• Multiple rooms with access controls
• Direct messages
• File attachments with previews
• Search functionality
• Notifications via Web Push
• @mentions
• API support for bot integrations

You can run Campfire using a pre-built Docker image which includes the web app, background jobs, caching, file serving, and SSL.

Pre-built image: ghcr.io/basecamp/once-campfire:latest

For detailed instructions on running the Docker image yourself, refer to the self-hosting guide.

To ensure a consistent backup of the SQLite database, you must first run the prepare-backup script inside the running container. This creates a snapshot in storage/backups/.

1. Create a database snapshot:

docker exec campfire script/admin/prepare-backup

(Use docker compose exec web if using Compose)

2. Archive the storage volume:

docker run --rm \
  --user root \
  --volume campfire:/rails/storage \
  --volume "$PWD":/backup \
  ghcr.io/basecamp/once-campfire:latest \
  tar czf "/backup/campfire-backup.tar.gz" -C /rails storage

The easiest way to self-host Campfire is using ONCE, which handles initial setup and automatic updates.

To install ONCE, run the following command on your target machine:

curl https://get.once.com | sh

Once installed, you can either select Campfire from the ONCE dashboard or deploy directly via the CLI using the following command:

once deploy ghcr.io/basecamp/once-campfire --host chat.example.com

Campfire can be deployed as a single-machine Docker container containing the web app, background jobs, caching, file serving, and SSL.

Recommended image: ghcr.io/basecamp/once-campfire:latest.

You can pin to specific versions using tags:

• Exact version: ghcr.io/basecamp/once-campfire:1.4.4
• Minor version: ghcr.io/basecamp/once-campfire:1.4
• Major version: ghcr.io/basecamp/once-campfire:1
• Bleeding edge: ghcr.io/basecamp/once-campfire:main

To build the image from source:

docker build -t campfire .

Start the development server using bin/dev. The application will be accessible at http://localhost:3000. On the first run, you will be prompted to create an admin account.

Note: Campfire requires Redis for Action Cable, caching, and background jobs. If Redis is not running, ensure the Docker container is started with docker start campfire-redis.

Since all state is stored in the mounted volume, upgrading is performed by pulling the new image and recreating the container. Database migrations run automatically on boot.

docker pull ghcr.io/basecamp/once-campfire:latest

Initialize the development environment by running the setup script. This installs required system packages (SQLite, ffmpeg), manages the Ruby version via mise, installs gems, prepares the database, and starts a Redis Docker container named campfire-redis. To perform a clean installation and reset the environment, use the --reset flag.

bin/setup
# Or to start over:
bin/setup --reset

Campfire stores its database and uploaded file attachments in /rails/storage. To persist data between container restarts, you must mount a volume to this path.

Use the --volume flag with docker run to create a named volume:

docker run --volume campfire:/rails/storage ghcr.io/basecamp/once-campfire:latest

Campfire requires specific secret values for cryptography and Web Push notifications. You can generate these using the built-in admin script:

docker run --rm ghcr.io/basecamp/once-campfire:latest script/admin/generate-secrets

This will output values for:

• SECRET_KEY_BASE
• VAPID_PRIVATE_KEY
• VAPID_PUBLIC_KEY

Warning: Keep these values safe and reuse them across restarts and upgrades. Changing them later will invalidate user sessions and push notification subscriptions.

To enable browser push notifications in development, you must provide VAPID (Voluntary Application Server Identification) keys via the following environment variables:

• VAPID_PRIVATE_KEY
• VAPID_PUBLIC_KEY

You can generate a new key pair using the provided admin script.

script/admin/generate-secrets