Local development.
HTTPS included.

Before you start

You need Docker Engine, Docker Compose v2 or newer, and a checkout of the CatProof Community Edition source. For a prebuilt image, follow the Community Edition quick start. Run commands from that checkout’s root, alongside compose.yaml. A host Python installation is not required for the Compose stack.

Get the source

Install and start Docker, then clone the public repository. Run the remaining commands from the repository root.

git clone https://github.com/cat-proof/catproof-community.git
cd catproof-community

Build a Docker image

To create an application image without starting the services, run:

docker build -t catproof-community:local .
docker images catproof-community

The final . selects the current directory as the build context. The build uses the repository’s Dockerfile and tags the result catproof-community:local. An application image alone does not start PostgreSQL or the local HTTPS proxy.

Run your custom image with the full stack

./community.sh init
CATPROOF_IMAGE=catproof-community:local docker compose up -d --no-build --wait

Windows PowerShell:

.\community.ps1 init
$env:CATPROOF_IMAGE = 'catproof-community:local'
docker compose up -d --no-build --wait

Keep selecting the same image with CATPROOF_IMAGE for future Compose operations. After startup, follow the local HTTPS trust instructions before browser sign-in. For the simpler build-and-run path, use the launcher’s --build option below.

Use a prebuilt image instead

docker pull ghcr.io/cat-proof/catproof-community:0.2.0

This downloads the application image only. Run ./community.sh start or .\community.ps1 start to configure and start the complete stack with the published image.

1. Generate local configuration

On the first run, create an ignored .env file with private permissions. This command refuses to overwrite an existing file. Keep the file and its key across restarts so saved connector credentials remain readable.

./community.sh init

2. Start the stack

./community.sh start --build

On Windows PowerShell, use .\community.ps1 start -Build. This launcher builds the application and starts all required services together.

The app starts with an empty PostgreSQL database. Development data persists in a Docker volume. Provider credentials from your host environment are not automatically imported.

3. Verify local HTTPS

Caddy uses its own local certificate authority. Export the public root certificate and check the health endpoint with that certificate.

docker compose exec -T web cat /data/caddy/pki/authorities/local/root.crt > /tmp/catproof-local-ca.crt
curl --cacert /tmp/catproof-local-ca.crt https://localhost:8443/healthz

For browser use, manually import and trust this certificate in your browser or OS trust store. Compose does not change the host trust store. Open https://localhost:8443/signup and create a personal account. HTTPS and Secure cookies remain enabled.

4. Run the integration suite

docker compose --profile test run --build --rm tests
docker compose --profile test stop test-db

The suite uses a separate disposable PostgreSQL test database. It does not use the app’s persistent database or contact vendor APIs. For a focused database test, run:

docker compose --profile test run --build --rm tests python -m unittest -v test_postgres_integration

5. Rebuild, inspect or stop

docker compose logs --tail=100 app web
docker compose down

docker compose down preserves development data and the local CA. Adding -v deletes those local volumes permanently. After source changes, rerun ./community.sh start --build; source is copied into the image rather than mounted live.

Community Edition source limit

Version 0.2.0 supports two saved, unarchived source connections per registry. Paused connections count. Archive an unwanted connection in Connected registries to free a slot while preserving records and history. Restoring uses a free slot and leaves the source paused.

Back up the database and preserve .env before upgrading to the h0008 schema. Older registries with more than two connections retain their evidence, with source reads limited to the two oldest unarchived connections. See the release’s operations guide for upgrade and rollback requirements.

Connecting providers locally

The Compose app retains hosted egress restrictions, so private-address provider endpoints are blocked. Use isolated integration fixtures to test peer transport. Do not weaken egress checks to connect a localhost fixture. Real provider connections still require authorized, publicly reachable HTTPS endpoints and credentials.

For existing database upgrades, back up the database and stop old writers before starting the new version. Read docs/DATABASE.md in the Community Edition checkout for migration and restore procedures.

Reviewed against the current product source on October 29, 2026. Provider access must be verified in your authorized account.