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: make the Kaneo docs the source of truth for drim

Andrejf040ebf1575b
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 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: 10
groups:
# 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.mdx
new file mode 100644
index 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.mdx
index 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:
-
```bash
curl -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
```bash
drim 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
```bash
drim 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.
+# Email
+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.json
index 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",