convertor/docs/local-deploy.md

Local Docker Deployment

This repository includes a dedicated Compose file for normal local usage without rebuilding the image from source.

Why use this instead of compose.yaml

• compose.local.yaml pulls the published ConvertX image
• compose.yaml builds from the local checkout and is intended for development and testing
• Keeping them separate makes upgrades easier and avoids accidentally coupling local usage to repository state

Prerequisites

• Docker Desktop or a compatible Docker Engine

First-time setup

1. Copy the example environment file:

cp .env.local.example .env.local

2. Set a long random JWT_SECRET in .env.local
3. Start the service:

docker compose --env-file .env.local -f compose.local.yaml up -d

4. Verify the service is healthy:

docker compose --env-file .env.local -f compose.local.yaml ps
curl -fsS http://127.0.0.1:3000/healthcheck

5. Open http://localhost:3000
6. Create the first account before exposing the service to anyone else

Useful operations

Start or update the container:

docker compose --env-file .env.local -f compose.local.yaml up -d

Stop the container:

docker compose --env-file .env.local -f compose.local.yaml down

View logs:

docker compose --env-file .env.local -f compose.local.yaml logs -f

Restart after changing configuration:

docker compose --env-file .env.local -f compose.local.yaml restart

Notes

• The persistent database and job files are stored in ./data
• HTTP_ALLOWED=true is appropriate for localhost usage
• CONVERTX_IMAGE defaults to the published release image and can be overridden if you need a different tag