Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

docs: add storage backends guide and update references for image uploads

Andrej3ef5f680b97b
diff --git a/apps/docs/core/installation/docker-compose.mdx b/apps/docs/core/installation/docker-compose.mdx
index 1df4b3991..6815ef35e 100644
--- a/apps/docs/core/installation/docker-compose.mdx
+++ b/apps/docs/core/installation/docker-compose.mdx
@@ -69,6 +69,7 @@ Kaneo uses S3-compatible object storage for image uploads in task descriptions a
- 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 images directly to the configured storage backend.
- 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](/core/installation/storage-backends).
### Optional MinIO service
diff --git a/apps/docs/core/installation/object-storage-and-image-uploads.mdx b/apps/docs/core/installation/object-storage-and-image-uploads.mdx
index 6ad535578..5414aa26a 100644
--- a/apps/docs/core/installation/object-storage-and-image-uploads.mdx
+++ b/apps/docs/core/installation/object-storage-and-image-uploads.mdx
@@ -15,6 +15,8 @@ Uploads use an S3-compatible object storage backend:
This means Kaneo can work with multiple backends as long as they expose a compatible S3-style API.
+If you want backend-specific setup examples, see the [storage backends guide](/core/installation/storage-backends).
+
## Recommended local setup: MinIO
For local or self-hosted deployments, MinIO is the recommended storage backend.
@@ -42,6 +44,48 @@ S3_FORCE_PATH_STYLE=true
Create the bucket before using uploads.
+## Important: internal Docker URLs are not enough in production
+
+When Kaneo generates a presigned upload URL, the browser uploads directly to your storage backend.
+
+That means `S3_ENDPOINT` must be reachable by the browser, not just by Docker containers.
+
+For example:
+
+- `http://minio:9000` works only inside Docker
+- `https://files.example.com` works from the browser
+
+If your Kaneo deployment is public, do not leave `S3_ENDPOINT` set to `http://minio:9000`.
+
+Use a public MinIO hostname instead, for example:
+
+```env
+S3_ENDPOINT=https://files.cloud.kaneo.app
+S3_BUCKET=kaneo-uploads
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=true
+S3_PUBLIC_BASE_URL=https://files.cloud.kaneo.app/kaneo-uploads
+```
+
+## Recommended public setup
+
+The simplest production setup is:
+
+- `cloud.kaneo.app` for Kaneo
+- `files.cloud.kaneo.app` for MinIO
+
+Expose MinIO on its own public hostname through your reverse proxy.
+
+Why this is needed:
+
+- Kaneo signs uploads against `S3_ENDPOINT`
+- the browser uses that signed URL directly
+- Docker-internal names like `minio` are not resolvable from a user's browser
+
+Using a dedicated subdomain is recommended over proxying MinIO under a path.
+
## Other S3-compatible backends
Kaneo is not tied to MinIO. Any deployment can point Kaneo at another S3-compatible backend by changing the `S3_*` environment variables.
@@ -107,5 +151,7 @@ If uploads fail:
- confirm the bucket exists
- confirm the credentials can write to the bucket
-- confirm the storage endpoint is reachable from the Kaneo API
+- confirm the storage endpoint is reachable from the browser
+- confirm `S3_ENDPOINT` is a public URL, not an internal Docker hostname
+- confirm `S3_PUBLIC_BASE_URL` matches the public asset host if you are using one
- if using direct browser uploads, confirm CORS is configured correctly for your storage endpoint
diff --git a/apps/docs/core/installation/storage-backends.mdx b/apps/docs/core/installation/storage-backends.mdx
new file mode 100644
index 000000000..4cbaee90d
--- /dev/null
+++ b/apps/docs/core/installation/storage-backends.mdx
@@ -0,0 +1,232 @@
+---
+title: Storage backends
+description: Configure image uploads with MinIO, AWS S3, or Cloudflare R2.
+---
+
+## Overview
+
+Kaneo uses S3-compatible object storage for image uploads in:
+
+- task descriptions
+- task comments
+
+The browser uploads directly to the configured storage backend using presigned URLs.
+
+That means one rule matters for every backend:
+
+- `S3_ENDPOINT` must be reachable by the browser
+
+Do not use a Docker-internal hostname such as `http://minio:9000` for a public deployment unless the browser can actually reach it.
+
+## Required Kaneo variables
+
+```env
+S3_ENDPOINT=
+S3_BUCKET=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=false
+S3_PUBLIC_BASE_URL=
+```
+
+Notes:
+
+- `S3_PUBLIC_BASE_URL` is recommended when your asset URL should be different from the raw S3 endpoint.
+- `S3_FORCE_PATH_STYLE=true` is usually needed for MinIO.
+- `S3_FORCE_PATH_STYLE=false` is usually correct for AWS S3 and R2.
+
+## MinIO
+
+MinIO is the recommended self-hosted option.
+
+### Local Docker setup
+
+For local development, this is fine:
+
+```env
+MINIO_ROOT_USER=minioadmin
+MINIO_ROOT_PASSWORD=minioadmin
+
+S3_ENDPOINT=http://minio:9000
+S3_BUCKET=kaneo-uploads
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=true
+S3_PUBLIC_BASE_URL=http://localhost:9000/kaneo-uploads
+```
+
+This works when Kaneo and MinIO are on the same Docker network and your browser reaches MinIO through `localhost`.
+
+### Public deployment
+
+For a public deployment, expose MinIO on its own hostname through your reverse proxy.
+
+Example:
+
+- Kaneo: `https://cloud.kaneo.app`
+- MinIO: `https://files.cloud.kaneo.app`
+
+This can be done with Caddy, Nginx, Traefik, or any other reverse proxy.
+
+Then use:
+
+```env
+S3_ENDPOINT=https://files.cloud.kaneo.app
+S3_BUCKET=kaneo-uploads
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=true
+S3_PUBLIC_BASE_URL=https://files.cloud.kaneo.app/kaneo-uploads
+```
+
+You also need:
+
+- a created bucket
+- MinIO CORS allowing your Kaneo origin
+
+## AWS S3
+
+AWS S3 is the simplest managed option.
+
+Use a bucket and an IAM user with access to that bucket.
+
+Example:
+
+```env
+S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
+S3_BUCKET=kaneo-uploads
+S3_ACCESS_KEY_ID=AKIA...
+S3_SECRET_ACCESS_KEY=...
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=false
+S3_PUBLIC_BASE_URL=https://kaneo-uploads.s3.us-east-1.amazonaws.com
+```
+
+For another AWS region, adjust both:
+
+- `S3_ENDPOINT`
+- `S3_PUBLIC_BASE_URL`
+
+Recommended S3 CORS policy:
+
+```json
+[
+ {
+ "AllowedHeaders": ["*"],
+ "AllowedMethods": ["GET", "PUT", "HEAD"],
+ "AllowedOrigins": ["https://cloud.kaneo.app"],
+ "ExposeHeaders": ["ETag"]
+ }
+]
+```
+
+## Cloudflare R2
+
+R2 works well because it exposes an S3-compatible API.
+
+Use your account endpoint, bucket, and R2 access keys.
+
+Example:
+
+```env
+S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+S3_BUCKET=kaneo-uploads
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+S3_REGION=auto
+S3_FORCE_PATH_STYLE=false
+S3_PUBLIC_BASE_URL=https://pub-<hash>.r2.dev
+```
+
+Notes:
+
+- `S3_REGION=auto` is typical for R2
+- `S3_PUBLIC_BASE_URL` should usually point to your public bucket domain or custom domain
+- if your bucket is not public, image rendering will not work from stored asset URLs
+
+## One copy-paste self-hosted example
+
+This example gives you Kaneo + MinIO in one Compose file.
+
+```yml
+services:
+ postgres:
+ image: postgres:16-alpine
+ env_file:
+ - .env
+ volumes:
+ - postgres_data:/var/lib/postgresql/data
+ restart: unless-stopped
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+
+ api:
+ image: ghcr.io/usekaneo/api:latest
+ env_file:
+ - .env
+ depends_on:
+ postgres:
+ condition: service_healthy
+ restart: unless-stopped
+
+ web:
+ image: ghcr.io/usekaneo/web:latest
+ env_file:
+ - .env
+ depends_on:
+ - api
+ restart: unless-stopped
+
+ minio:
+ image: minio/minio:latest
+ command: server /data --console-address ":9001"
+ env_file:
+ - .env
+ volumes:
+ - minio_data:/data
+ restart: unless-stopped
+
+volumes:
+ postgres_data:
+ minio_data:
+```
+
+Matching `.env`:
+
+```env
+KANEO_CLIENT_URL=https://cloud.kaneo.app
+KANEO_API_URL=https://cloud.kaneo.app/api
+
+MINIO_ROOT_USER=minioadmin
+MINIO_ROOT_PASSWORD=change-me
+
+S3_ENDPOINT=https://files.cloud.kaneo.app
+S3_BUCKET=kaneo-uploads
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=change-me
+S3_REGION=us-east-1
+S3_FORCE_PATH_STYLE=true
+S3_PUBLIC_BASE_URL=https://files.cloud.kaneo.app/kaneo-uploads
+```
+
+Before testing uploads:
+
+1. Create the `kaneo-uploads` bucket.
+2. Configure MinIO CORS for your Kaneo origin.
+3. Make sure `files.cloud.kaneo.app` resolves publicly.
+
+## Troubleshooting
+
+If uploads fail:
+
+- check that the bucket exists
+- check that `S3_ENDPOINT` is public and browser-reachable
+- check that `S3_PUBLIC_BASE_URL` points to the correct public asset host
+- check CORS on your storage backend
+- check that the access key can `PutObject` and `GetObject`
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 9d66129d4..e73f69955 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -66,6 +66,7 @@
"core/installation/drim",
"core/installation/docker-compose",
"core/installation/object-storage-and-image-uploads",
+ "core/installation/storage-backends",
"core/installation/environment-variables",
"core/installation/start-services"
]