⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
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.mdxindex 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 servicediff --git a/apps/docs/core/installation/object-storage-and-image-uploads.mdx b/apps/docs/core/installation/object-storage-and-image-uploads.mdxindex 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: MinIOFor local or self-hosted deployments, MinIO is the recommended storage backend.@@ -42,6 +44,48 @@ S3_FORCE_PATH_STYLE=trueCreate 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 backendsKaneo 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 endpointdiff --git a/apps/docs/core/installation/storage-backends.mdx b/apps/docs/core/installation/storage-backends.mdxnew file mode 100644index 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.jsonindex 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"]