Skip to main content

​
The initial compose file

The first step is to create a Docker Compose file. We will call it compose.yml.

​
The services and volumes

Kaneo uses the following services:
  • postgres: The PostgreSQL database.
  • kaneo: The combined API and web container.
Additionally, the following volumes are used:
  • postgres_data: The PostgreSQL data.

​
Required URL configuration

Copy .env.sample to .env and uncomment or set these values:
KANEO_API_URL defaults to KANEO_CLIENT_URL/api; set it explicitly only if you need to override the default (e.g. a reverse proxy changes the path). This keeps the browser on one origin while the container proxies /api requests to the internal API process. For this Compose setup, the bundled Kaneo container reaches PostgreSQL at the service hostname postgres. If you run the API directly on your host instead, use localhost or set DATABASE_URL explicitly.

​
Notes on object storage

Kaneo uses S3-compatible object storage for private uploads in task descriptions and comments.
  • Object storage is optional. Kaneo runs without it, but uploads in task descriptions and comments will be unavailable.
  • For local/self-hosted setups, MinIO is the recommended option when you want uploads.
  • The Kaneo API creates presigned upload URLs and the browser uploads files directly to the configured storage backend.
  • Kaneo serves uploaded assets back through its own API, so the bucket does not need to be public.
  • If you do not configure object storage, leave the S3_* variables unset.
  • For a complete MinIO example and backend-specific setup notes, see the storage backends guide.

​
Optional MinIO service

Add this service and volume to your compose.yml only if you want uploads:
Set the matching S3_* environment variables in your .env file. See the environment variables page.

​
Example .env values for MinIO

Create the bucket before testing uploads. With MinIO, you can do that from the MinIO Console at http://localhost:9001.

​
Using fs instead of MinIO

If you want to use fs, you can point the same S3_* variables at its endpoint instead of MinIO. Kaneo only needs an S3-compatible API endpoint, credentials, and a bucket. When using fs, keep these differences in mind:
  • Set S3_FORCE_PATH_STYLE=true.
  • Create buckets through the S3 API or CLI, not through a web console.
  • Browser uploads may require reverse-proxy CORS handling, because fs does not currently implement S3 CORS APIs.
After creating the compose file, the next step is to set up the environment variables.