⚡ 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: make the Kaneo docs the source of truth for drim
Andrejf040ebf1575b
diff --git a/.github/dependabot.yml b/.github/dependabot.ymlindex 3ef593ea6..da1de32a8 100644--- a/.github/dependabot.yml+++ b/.github/dependabot.yml@@ -9,6 +9,8 @@ updates:directory: "/"schedule:interval: "weekly"+ commit-message:+ prefix: "chore(deps)"open-pull-requests-limit: 10groups:# Batch all non-major updates into a single PR to minimise lockfile churn.@@ -19,3 +21,10 @@ updates:update-types:- "minor"- "patch"++ - package-ecosystem: "github-actions"+ directory: "/"+ schedule:+ interval: "weekly"+ commit-message:+ prefix: "ci(deps)"diff --git a/apps/docs/core/installation/drim-migration.mdx b/apps/docs/core/installation/drim-migration.mdxnew file mode 100644index 000000000..ac69ba39a--- /dev/null+++ b/apps/docs/core/installation/drim-migration.mdx@@ -0,0 +1,178 @@+---+title: Migrating to drim+description: Move an existing Kaneo deployment onto the drim CLI, or update an older drim deployment to the current single-container layout+---++Two migrations are covered here. Both reuse your existing Docker volumes, so your database+and uploads stay where they are and no data is copied.++## Updating an older drim deployment++Kaneo used to ship as two images, `api` and `web`, behind a reverse proxy that split+traffic between them. It now ships as one container that serves the web app and the API+together.++`drim upgrade` pulls new images but does not rewrite an existing `docker-compose.yml`, so a+deployment created before that change keeps running the old layout indefinitely. Check+which one you have:++```bash+grep -E 'image:.*usekaneo' docker-compose.yml+```++Two lines with `usekaneo/api` and `usekaneo/web` mean you are on the old layout. A single+`usekaneo/kaneo` line means you are already current and there is nothing to do.++### Steps++Back up the files you are about to edit, so you can put them back:++```bash+STAMP=$(date +%Y%m%d-%H%M%S)+cp docker-compose.yml docker-compose.yml.bak-$STAMP+cp Caddyfile Caddyfile.bak-$STAMP+```++Pull the image first, so the switchover is a quick container swap rather than a download:++```bash+docker pull ghcr.io/usekaneo/kaneo:latest+```++Replace the `api` and `web` services in `docker-compose.yml` with one `kaneo` service.+Leave `postgres`, the volumes, and any services you added yourself untouched:++```yaml+ kaneo:+ image: ghcr.io/usekaneo/kaneo:latest+ env_file: .env+ depends_on:+ postgres:+ condition: service_healthy+ restart: unless-stopped+ healthcheck:+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:5173/api/health"]+ interval: 30s+ timeout: 5s+ start_period: 60s+ retries: 3+ networks:+ - kaneo+```++Update anything that pointed at the old services. In `depends_on` entries elsewhere,+replace `api` and `web` with `kaneo`. In your reverse proxy, send everything to the one+service instead of splitting on path, because the container routes `/api` internally:++```caddyfile+your-domain.com {+ reverse_proxy http://kaneo:5173+ encode gzip+}+```++Apply it:++```bash+docker compose up -d --remove-orphans+```++<Warning>+If your reverse proxy config is bind-mounted as a single file, recreate that container+rather than reloading it. Replacing the file with `mv` gives it a new inode, and the+running container keeps reading the old one, so a reload silently applies stale config:++```bash+docker compose up -d --force-recreate caddy+```+</Warning>++### Verify++```bash+docker compose ps+curl -s https://your-domain.com/api/health+```++You want every service up, the Kaneo container reporting healthy once its start period+elapses, and `{"status":"ok"}` from the health endpoint.++### Rollback++Restore the backed-up files and recreate:++```bash+cp docker-compose.yml.bak-$STAMP docker-compose.yml+cp Caddyfile.bak-$STAMP Caddyfile+docker compose up -d --force-recreate+```++## Moving an existing Kaneo onto drim++If you deployed Kaneo by hand and want drim to manage it, the goal is to have drim generate+its files and then point them at the volumes you already have.++Record the names of your existing volumes and your current environment values:++```bash+docker volume ls | grep -i kaneo+```++Stop the current stack, then install drim and run setup in a new directory:++```bash+docker compose down+curl -fsSL https://assets.kaneo.app/install.sh | sh+mkdir ~/kaneo && cd ~/kaneo+drim setup --domain=your-domain.com+drim stop+```++Point the generated `docker-compose.yml` at your existing database volume by declaring it+external, using the exact name from `docker volume ls`:++```yaml+volumes:+ postgres_data:+ external: true+ name: your_existing_volume_name+```++Copy your previous credentials into the generated `.env`, in particular `POSTGRES_USER`,+`POSTGRES_PASSWORD`, `POSTGRES_DB`, `DATABASE_URL` and `AUTH_SECRET`. A different+`AUTH_SECRET` invalidates every existing session, so reuse the old value unless you intend+to sign everyone out.++```bash+drim configure # opens .env, applies changes on save+```++Then start and verify as above.++### Using your own reverse proxy++If you already run nginx, Traefik or similar, choose `--no-reverse-proxy` at setup so drim+does not start Caddy on ports 80 and 443, and point your proxy at Kaneo on port 5173.++## Common issues++**Database connection failed.** The credentials in `.env` do not match the ones the volume+was created with. `DATABASE_URL` must agree with `POSTGRES_USER`, `POSTGRES_PASSWORD` and+`POSTGRES_DB`.++**Volume not found.** The `name:` under an external volume must match `docker volume ls`+exactly, including any project-name prefix from the old deployment.++**Port already in use.** Something else holds 80 or 443, usually a system nginx or the old+stack still running. Stop it, or use `--no-reverse-proxy`.++**Everyone was signed out.** `AUTH_SECRET` changed. Restore the previous value.++## After migrating++Keep the old containers' volumes until you are confident, then remove the stale containers+and images. Volumes are the only thing holding your data, so remove those last and+deliberately.++Set up off-site backups if you have not already. A copy on the same machine does not+survive losing that machine.diff --git a/apps/docs/core/installation/drim.mdx b/apps/docs/core/installation/drim.mdxindex fff82b76b..e3f7ce5bf 100644--- a/apps/docs/core/installation/drim.mdx+++ b/apps/docs/core/installation/drim.mdx@@ -1,112 +1,179 @@---title: Deploy with drim CLI-description: One-click deployment tool for self-hosted Kaneo instances+description: Deploy and manage a self-hosted Kaneo instance with the drim CLI---## What is drim?-[drim](https://github.com/usekaneo/drim) is a CLI tool for deploying your Kaneo instances. It's designed for fairly straightforward setups where you want to get Kaneo up and running quickly without manual configuration.+[drim](https://github.com/usekaneo/drim) is a CLI tool for deploying Kaneo. It generates+your `docker-compose.yml`, `Caddyfile` and `.env`, installs Docker if it is missing, and+brings the stack up, so a fresh server goes from nothing to a running instance in one+command.-drim handles:-- Docker Compose file generation-- Environment variable setup-- Automatic HTTPS with Caddy-- Service management (start, stop, restart)-- Updates and upgrades+It suits straightforward deployments. If you need a custom topology, extra services, or+your own reverse proxy, [Docker Compose](/core/installation/docker-compose) gives you more+control.## Installation-Install drim with a single command:-```bashcurl -fsSL https://assets.kaneo.app/install.sh | sh```-Or download the binary manually from [releases](https://github.com/usekaneo/drim/releases/latest).+Or download a binary from [releases](https://github.com/usekaneo/drim/releases/latest).++### Install script options++| Option | Description |+| --- | --- |+| `--silent` | Suppress output |+| `--setup` | Run `drim setup` after installing |+| `--domain=DOMAIN` | Deploy on this domain, implies `--setup` |-## Quick Start+```bash+# Install, deploy, and configure HTTPS for a domain in one command+curl -fsSL https://assets.kaneo.app/install.sh | sh -s -- --setup --domain=kaneo.example.com+```-### Local Development+The script detects your platform, downloads the matching binary, and installs it to+`/usr/local/bin`. It supports Linux and macOS on amd64 and arm64, and Windows through WSL.-For local development without a domain:+## Quick start++### Interactive```bashdrim setup-# Press Enter when prompted for domain-# Access at http://localhost```-### Production Deployment+You are asked whether to use the bundled Caddy reverse proxy, and for a domain. Leave the+domain empty for a local deployment, reachable at `http://localhost`, or+`http://localhost:5173` when you skip the reverse proxy.++### Non-interactive-For production with automatic HTTPS:+Pass the configuration as flags to skip the prompts, which is what you want in a script or+over SSH without a terminal:```bash-drim setup-# Enter your domain when prompted (e.g., kaneo.example.com)-# Access at https://your-domain.com+drim setup --domain=kaneo.example.com+drim setup --no-reverse-proxy```<Info>-Make sure your domain's DNS A record points to your server before running setup.+Point your domain's DNS A record at the server before running setup. Caddy requests a+certificate immediately, and that only succeeds once the record resolves.</Info>## Commands-drim provides several commands to manage your Kaneo instance:-```bash-drim setup # Deploy Kaneo-drim start # Start services-drim stop # Stop services-drim restart # Restart services-drim upgrade # Update Kaneo to latest version-drim update # Update drim CLI to latest version-drim configure # Edit configuration-drim uninstall # Remove Kaneo+drim setup # Deploy Kaneo+drim start # Start services+drim stop # Stop services+drim restart # Restart services+drim upgrade # Pull the latest Kaneo images and restart+drim update # Update the drim CLI itself+drim configure # Edit .env, then apply the changes+drim uninstall # Remove Kaneo```-## What Gets Installed+Run these from the directory holding your `docker-compose.yml`. drim tells you when it+cannot find a deployment there.-When you run `drim setup`, the following services are deployed:+`drim restart` restarts the containers. Because services read configuration through+`env_file`, a plain restart reuses the environment a container was created with, so use+`drim restart --recreate` to recreate containers and pick up `.env` changes. `drim+configure` already does this for you.-- **PostgreSQL 16** - Database-- **Kaneo** - Combined API and web frontend in a single container-- **Caddy** - Reverse proxy with automatic HTTPS+## What gets installed-All services run in Docker containers with proper networking and health checks.+- **PostgreSQL 16**, the database+- **Kaneo**, the API and web app in a single container+- **Caddy**, the reverse proxy with automatic HTTPS, unless you pass `--no-reverse-proxy`-## Configuration+Services run with health checks and restart automatically unless explicitly stopped.+PostgreSQL is only reachable on the internal Docker network, never published to the host.-To edit environment variables after setup:+## Configuration```bashdrim configure```-This opens `.env` in your default editor. After saving, services are restarted automatically.+This opens `.env` in `$EDITOR` (or nano). After saving, drim offers to apply the changes,+which recreates the containers so the new values take effect.++`drim setup` writes the variables Kaneo requires. Optional features are enabled by adding+their variables, for example:++```env+# GitHub sign-in+GITHUB_OAUTH_CLIENT_ID=your_client_id+GITHUB_OAUTH_CLIENT_SECRET=your_client_secret-See the [environment variables documentation](/core/installation/environment-variables) for available options.+SMTP_HOST=smtp.example.com+SMTP_PORT=587+SMTP_PASSWORD=your-password++# Redis pub/sub, for running more than one API replica+REDIS_URL=redis://your-redis-host:6379+```++See [environment variables](/core/installation/environment-variables) for the full list.## Requirements-- Docker 20.10+-- Docker Compose V2-- 2GB RAM minimum-- 10GB disk space+- Docker 20.10+ and Docker Compose V2+- 2GB RAM and 10GB disk+- A public DNS record, for production deployments-**Supported Platforms:** Linux, macOS, Windows (WSL)+drim installs Docker automatically on supported Linux distributions. When it does, it also+adds your user to the `docker` group and stops, because group membership only applies to a+new login session. Log out, log back in, and run `drim setup` again.-<Info>-drim will attempt to install Docker automatically on supported Linux distributions.-</Info>+If Docker is already installed but you are not in the `docker` group, setup tells you so+before writing any files, along with the command to fix it:++```bash+sudo usermod -aG docker $USER+```++## Upgrading++```bash+drim upgrade+```++This pulls the latest images and restarts the changed services. Your data lives in Docker+volumes and is not touched.-## When to Use drim+To update drim itself:++```bash+drim update+```++<Warning>+Deployments created before Kaneo moved to a single container still run the older two-image+layout, and `drim upgrade` does not rewrite an existing `docker-compose.yml`. See+[migrating to drim](/core/installation/drim-migration) to move to the current layout.+</Warning>++## Building from source++```bash+git clone https://github.com/usekaneo/drim.git+cd drim+go build -o drim .+```-drim is ideal for:+`make build-all` cross-compiles for every supported platform.-- Quick local development setups-- Simple production deployments with a single domain-- Teams that want automatic HTTPS without manual configuration-- Anyone who wants to get Kaneo running with minimal effort+## Getting help-For more complex setups (multiple domains, custom networking, Kubernetes, etc.), see the [manual Docker Compose installation](/core/installation/docker-compose).+- [Report an issue](https://github.com/usekaneo/drim/issues)+- [Discord](https://discord.gg/rU4tSyhXXU)diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex b25b59d25..b87a6c057 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -66,6 +66,7 @@"pages": ["core/installation/index","core/installation/drim",+ "core/installation/drim-migration","core/installation/docker-compose","core/installation/object-storage-and-image-uploads","core/installation/storage-backends",