Customizing Your Deployment

Pinchy’s docker-compose.yml is owned by the Pinchy project and gets replaced whenever you upgrade. If you customize it directly, your changes disappear on the next curl -o docker-compose.yml ....

The supported customization surface is docker-compose.override.yml — a file you create in the same directory as docker-compose.yml. Docker Compose automatically merges it on top of the base file, every time you run docker compose up. Upgrades never touch it.

Note

If you edit docker-compose.yml directly, your changes will be lost on the next upgrade. Always customize via docker-compose.override.yml instead.

Recipe 1: Extra environment variables

Add debug flags or optional Pinchy variables that aren’t in .env.example:

docker-compose.override.yml

services:
  pinchy:
    environment:
      - DEBUG=pinchy:*
      - SOME_OPTIONAL_FLAG=true

Compose merges this with the base environment: block — existing variables are kept, new ones are added. For duplicate keys, the override wins. See the Docker Compose merge docs for edge cases.

Recipe 2: Expose the database for an external tool

If you want to connect psql or DBeaver from the same host for debugging:

docker-compose.override.yml

services:
  db:
    ports:
      - "127.0.0.1:5432:5432"

Caution

Bind to 127.0.0.1:5432, not 0.0.0.0:5432 or just 5432. Docker bypasses host firewalls (UFW), so binding to all interfaces exposes Postgres to the internet regardless of your firewall rules.

Remove the override when you’re done debugging.

Recipe 3: Mount additional OpenClaw extensions

If you’ve written a custom OpenClaw plugin and want it loaded alongside the bundled Pinchy plugins:

docker-compose.override.yml

services:
  openclaw:
    volumes:
      - /opt/my-extensions:/root/.openclaw/extensions/custom:ro

Mount read-only (:ro) when possible — OpenClaw reads extensions at startup; it doesn’t need write access.

What’s not supported

The override file is for additions, not replacements. The following are outside the supported surface and may break on any release:

• Replacing the image: on either pinchy or pinchy-openclaw with a different image
• Renaming volumes, services, or networks
• Rewiring inter-service dependencies or health checks
• Changing the Postgres image to a non-17 version

If you find yourself needing any of these, open an issue — your use case might belong in core Pinchy rather than in an override.

Testing overrides

Before running docker compose up -d, check the merged config:

docker compose config

This prints the effective configuration (base + override merged) without starting anything. Use it to verify your override does what you expect.

Overrides and upgrades

Your docker-compose.override.yml survives upgrades unchanged. However, if a new Pinchy release changes a base-file field you’re overriding (for example, renames a volume), the merge may produce an unexpected result. Re-check docker compose config after every major release.