2026-09-02 01:05:41 +08:00
commit 04bac1f6e2
2200 changed files with 489415 additions and 0 deletions
@@ -0,0 +1,29 @@
---
title: "Deploy on AWS"
description: "Run OpenWork on Amazon EKS with Amazon RDS for MySQL."
---
The recommended AWS path is Helm on Amazon EKS with Amazon RDS for MySQL. For the smallest first deployment, use EKS Auto Mode and Kubernetes `LoadBalancer` Services so AWS provisions Network Load Balancers for Den web and Den API. Move to an ALB or an existing ingress platform when you need shared layer-7 routing, WAF policy, or more advanced certificate handling.
## What AWS manages
- EKS control plane, compute, pod networking, and load-balancer integration
- VPCs, subnets, routing, security groups, and IAM
- RDS for MySQL, encryption, backups, and failover
- Route 53 DNS and ACM certificates when you use those services
The OpenWork chart manages Deployments, Services, ConfigMaps, Secret references, probes, and the database migration Job.
## AWS checklist
1. Create an EKS Auto Mode cluster with `eksctl` `0.195.0` or newer.
2. Create an RDS MySQL 8-compatible database in private subnets.
3. Allow database port `3306` only from the EKS workload or node security boundary.
4. Store `DATABASE_URL`, `BETTER_AUTH_SECRET`, and `DEN_DB_ENCRYPTION_KEY` in a Kubernetes Secret.
5. Start from the chart's `values.aws-load-balancer.yaml` example.
6. Install the chart, verify migrations and readiness, then point DNS at the generated load balancers.
7. Enable trusted HTTPS before creating the first administrator.
For exact CLI commands, values, DNS/TLS choices, migration troubleshooting, verification, and cleanup, follow the [AWS EKS operator runbook](https://github.com/different-ai/openwork/blob/dev/docs/aws-eks-helm.md).
Next: [Create the first administrator](/self-host/deploy-to-your-cloud/first-administrator).
@@ -0,0 +1,29 @@
---
title: "Deploy on Azure"
description: "Run OpenWork on Azure Kubernetes Service with Azure Database for MySQL."
---
The recommended Azure path is Helm on Azure Kubernetes Service with Azure Database for MySQL Flexible Server. Use the AKS application-routing add-on's managed NGINX Ingress controller for browser-facing HTTPS and host routing.
## What Azure manages
- AKS control plane, node pools, virtual networking, and managed identities
- the managed NGINX ingress entry point and public IP
- Azure Database for MySQL Flexible Server, encryption, backups, and failover
- Azure DNS and certificate storage when you use those services
The OpenWork chart manages Deployments, Services, ConfigMaps, Secret references, probes, the Ingress, and the database migration Job.
## Azure checklist
1. Confirm the subscription is enabled and register the required resource providers.
2. Check regional vCPU quota and MySQL Flexible Server availability before creating AKS.
3. Create AKS and MySQL in a VNet topology that permits private database traffic.
4. Store `DATABASE_URL`, `BETTER_AUTH_SECRET`, and `DEN_DB_ENCRYPTION_KEY` in a Kubernetes Secret.
5. Start from the chart's `values.azure-ingress.yaml` example.
6. Configure the ingress certificate, install the chart, and verify migrations and readiness.
7. Point both hostnames at the ingress address and confirm trusted HTTPS.
For exact Azure CLI commands, values, TLS options, migration troubleshooting, verification, and cleanup, follow the [Azure AKS operator runbook](https://github.com/different-ai/openwork/blob/dev/docs/azure-aks-helm.md).
Next: [Create the first administrator](/self-host/deploy-to-your-cloud/first-administrator).
@@ -0,0 +1,52 @@
---
title: "Create the first administrator"
description: "Securely claim a new private OpenWork deployment without enabling public signup."
---
A private deployment should start with public signup disabled. Configuring an email in the owner or platform-admin allowlist authorizes that identity after authentication; it does not create an account, choose a password, or generate a default administrator password.
Releases that include initial-administrator bootstrap provide a dedicated setup page at:
```text
https://<your-den-web-host>/setup
```
<Warning>
  Chart versions without `/setup` do not support this private bootstrap flow. Upgrade before attempting first-user setup. Entering an allowlisted email on the normal sign-in page cannot create a missing account.
</Warning>
## Before installing
1. Configure the initial administrator email as an eligible singleton-organization owner.
2. Add the same email to the platform-admin allowlist only if that person also needs deployment-wide `/admin` access.
3. Generate a unique one-time setup code.
4. Inject the code through a Kubernetes Secret or your platform's secret store as `DEN_INITIAL_ADMIN_BOOTSTRAP_CODE`, or mount it from a file and set `DEN_INITIAL_ADMIN_BOOTSTRAP_CODE_FILE`.
5. Keep public signup disabled.
The setup code is a plain secret string, not a hash or token generated by OpenWork. Never place the real setup code in a committed Helm values file, ConfigMap, container image, source-control file, support ticket, screenshot, logs, or PR.
## Complete setup
1. Wait until Den web, Den API, and the migration Job are healthy.
2. Open `/setup` on the Den web hostname.
3. Enter the configured administrator email and the one-time setup code.
4. Choose the administrator's name and password.
5. Confirm that OpenWork signs the administrator in and opens the singleton organization.
The setup flow uses the existing Better Auth password and session protections. Successful setup creates the first account, creates or claims the singleton organization, grants the configured owner and platform-admin roles, and makes setup unavailable because the deployment now has a user.
## Verify the boundary
After setup:
- revisiting `/setup` reports that setup is complete or unavailable;
- the one-time code cannot create another administrator;
- unknown users still cannot sign up;
- the administrator can sign out and use normal password sign-in;
- restarting or scaling Den API does not re-enable setup.
If the deployment already contains a user, bootstrap remains unavailable even if its setup Secret still exists. Rotating or restoring the Secret does not reopen setup unless an operator deliberately changes the database outside OpenWork.
## Configure SSO next
Use the first owner as a break-glass account, then configure SAML or OIDC SSO and SCIM for normal workforce access. Protect the break-glass identity and recovery material according to your organization's access-control policy.
@@ -0,0 +1,29 @@
---
title: "Deploy on Google Cloud"
description: "Run OpenWork on GKE Autopilot with Cloud SQL for MySQL."
---
The recommended Google Cloud path is Helm on a regional GKE Autopilot cluster with Cloud SQL for MySQL. Use GKE Ingress, a reserved global IP address, Google-managed certificates, and explicit backend health checks for Den web and Den API.
## What Google Cloud manages
- GKE control plane and Autopilot compute lifecycle
- VPC networking, Cloud Load Balancing, firewall rules, and IAM
- Cloud SQL for MySQL, encryption, backups, and failover
- Cloud DNS and Google-managed certificates when you use those services
The OpenWork chart manages Deployments, Services, ConfigMaps, Secret references, probes, the Ingress, and the database migration Job. GKE `BackendConfig` and `ManagedCertificate` resources are applied alongside the chart.
## Google Cloud checklist
1. Enable the Kubernetes Engine, Compute Engine, Cloud SQL Admin, and Service Networking APIs.
2. Create a regional GKE Autopilot cluster and install `gke-gcloud-auth-plugin` if your Cloud SDK does not include it.
3. Configure private services access and create Cloud SQL for MySQL with a private IP.
4. Reserve a global IPv4 address and create the GKE health-check and certificate resources.
5. Store `DATABASE_URL`, `BETTER_AUTH_SECRET`, and `DEN_DB_ENCRYPTION_KEY` in a Kubernetes Secret.
6. Start from the chart's `values.gcp-ingress.yaml` example, install the chart, and verify migrations and readiness.
7. Point both hostnames at the reserved address and wait for the managed certificate to become active.
For exact `gcloud` commands, values, health checks, migration troubleshooting, verification, and cleanup, follow the [GKE operator runbook](https://github.com/different-ai/openwork/blob/dev/docs/gcp-gke-helm.md).
Next: [Create the first administrator](/self-host/deploy-to-your-cloud/first-administrator).
@@ -0,0 +1,61 @@
---
title: "Deploy to your cloud"
description: "Run OpenWork in your AWS, Azure, or Google Cloud account with Kubernetes, Helm, and managed MySQL."
---
OpenWork's supported private-cloud shape uses the published Helm chart, a managed Kubernetes cluster, and a MySQL-compatible database in your own account. You control the network, DNS, certificates, database, backups, identity provider, and secrets; the chart deploys Den web, Den API, migrations, and the optional inference service.
<CardGroup cols={3}>
  <Card title="AWS" icon="cloud" href="/self-host/deploy-to-your-cloud/aws">
    Deploy on EKS with Amazon RDS for MySQL.
  </Card>
  <Card title="Azure" icon="cloud" href="/self-host/deploy-to-your-cloud/azure">
    Deploy on AKS with Azure Database for MySQL.
  </Card>
  <Card title="Google Cloud" icon="cloud" href="/self-host/deploy-to-your-cloud/google-cloud">
    Deploy on GKE with Cloud SQL for MySQL.
  </Card>
</CardGroup>
## Common architecture
Every provider guide uses the same OpenWork boundaries:
- Den web listens on port `3005` and serves the browser experience.
- Den API listens on port `8788` and owns authentication, organizations, policy, and control-plane APIs.
- A MySQL 8-compatible database stores shared control-plane state.
- A migration Job runs before the application rollout.
- The inference service is optional and disabled by default.
- HTTPS hostnames expose web and API traffic through the provider's load-balancing layer.
Use private database networking in production. Require TLS for public application traffic, encrypt storage and backups, and keep database and authentication secrets in the provider secret store or a Kubernetes Secret—not in a Helm values file.
## Deployment sequence
1. Create the Kubernetes cluster and private MySQL database in compatible networks.
2. Reserve the public address or load-balancer entry point.
3. Create the database, database user, and Kubernetes namespace.
4. Generate independent database, Better Auth, and Den encryption secrets.
5. Prepare provider-specific Helm values for the web and API hostnames.
6. Install or upgrade the chart and wait for the migration Job and workloads.
7. Point DNS at the load balancer and verify trusted HTTPS.
8. [Create the first administrator](/self-host/deploy-to-your-cloud/first-administrator).
9. Configure SAML or OIDC SSO and invite or provision members.
## Before you start
You need:
- a cloud account with permission to create Kubernetes, networking, load-balancing, managed MySQL, DNS, certificates, and secrets;
- `kubectl` and Helm, plus the provider CLI and Kubernetes authentication plugin;
- two DNS names, normally one for Den web and one for Den API;
- a real email address for the initial owner;
- a backup, restore, upgrade, and rollback plan.
<Note>
  The provider pages give the supported architecture and point to the repository's detailed operator runbooks for exact commands. Pin a chart version in production and use the runbook from the matching release or branch.
</Note>
## After deployment
Use [Private network deployment](/start-here/private-network-deployment) when Den is reachable only through a VPN or private network. Review [Outbound network access](/start-here/outbound-network-access), [Certificate trust and proxies](/start-here/certificate-trust-and-proxies), and [Air-gapped deployment](/start-here/air-gapped-deployment) before restricting egress.
@@ -0,0 +1,112 @@
---
title: "Evaluate with Docker Compose"
description: "Run the OpenWork control plane from published images without cloning or building the repository."
---
Use the pull-only Docker Compose stack to evaluate Den web, Den API, and organization management on one machine. The stack downloads published OpenWork images and MySQL, runs database migrations, and starts the browser experience at `http://localhost:3005`.
<Warning>
  This stack is for evaluation only. Its HTTP ports bind to loopback, but it enables public signup by default, uses development credentials, keeps MySQL on one local Docker volume, and uses a stub worker provisioner. Do not change the port bindings to expose it on a network or use it for production data.
</Warning>
## Before you start
Install Docker Engine or Docker Desktop with Docker Compose v2. The machine must be able to pull images from GitHub Container Registry and Docker Hub.
## Start the stack
1. Download the Compose file into an empty directory:
   ```bash
   curl -fsSLo docker-compose.eval.yml \
     https://raw.githubusercontent.com/different-ai/openwork/9f8645ebc482c15ab99c0cf155aabaa411e1ca6a/packaging/docker/docker-compose.eval.yml
   printf '%s  %s\n' \
     '69cc7f2666157b7697ebf69b31b0c83887dd99e796c7d956f9ccaab8fa8bf2fc' \
     'docker-compose.eval.yml' | shasum -a 256 --check
   ```
   Continue only when the checksum command prints `docker-compose.eval.yml: OK`. The commit-specific URL and checksum ensure you run the reviewed Compose definition rather than the latest content of a mutable branch.
2. Start the services and wait for their health checks:
   ```bash
   umask 077
   printf 'OPENWORK_AUTH_SECRET=%s\nOPENWORK_DB_ENCRYPTION_KEY=%s\n' \
     "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
   docker compose -f docker-compose.eval.yml up -d --wait
   ```
3. Open [http://localhost:3005](http://localhost:3005) and create an account.
The stack exposes Den web on `127.0.0.1:3005` and Den API on `127.0.0.1:8788`. MySQL is reachable only inside the Compose network.
## Configure the evaluation
Set variables in your shell before running `docker compose`, or save them in a `.env` file beside `docker-compose.eval.yml`.
| Variable | Default | Purpose |
| --- | --- | --- |
| `OPENWORK_WEB_PORT` | `3005` | Host port for Den web. |
| `OPENWORK_API_PORT` | `8788` | Host port for Den API. |
| `OPENWORK_AUTH_SECRET` | Required | Better Auth signing secret of at least 32 random characters. |
| `OPENWORK_DB_ENCRYPTION_KEY` | Required | Key of at least 32 random characters used to encrypt selected database values. |
| `OPENWORK_ORG_NAME` | `OpenWork Evaluation` | Name of the single organization. |
| `OPENWORK_ALLOW_SIGNUP` | `true` | Whether anyone who can reach the site can create an account. |
The setup command writes unique secrets to `.env` so subsequent Compose commands reuse them. Keep this file private and do not commit it. To rotate the secrets, replace their values before recreating the services.
The Compose file pins the MySQL, Den API, and Den web images to immutable digests. Download a newer Compose file to evaluate a newer release rather than changing only an image tag.
If you create `.env` separately, generate unique secrets with:
```bash
umask 077
printf 'OPENWORK_AUTH_SECRET=%s\nOPENWORK_DB_ENCRYPTION_KEY=%s\n' \
  "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
```
## Connect from another machine
Keep the Compose ports bound to loopback. To evaluate a stack running on a remote host, create an encrypted SSH tunnel from your local machine:
```bash
ssh -N \
  -L 3005:127.0.0.1:3005 \
  -L 8788:127.0.0.1:8788 \
  user@docker-host
```
Then open [http://localhost:3005](http://localhost:3005). Authentication and API traffic travel through the SSH tunnel rather than across the network as plaintext HTTP.
## Inspect or stop the stack
View service state and logs:
```bash
docker compose -f docker-compose.eval.yml ps
docker compose -f docker-compose.eval.yml logs -f
```
Stop the services while retaining the evaluation database:
```bash
docker compose -f docker-compose.eval.yml down
```
Stop the services and permanently delete the evaluation database:
```bash
docker compose -f docker-compose.eval.yml down -v
```
## Evaluation limitations
The stack does not provide:
- production worker provisioning or cloud sandboxes;
- transactional email or email verification;
- TLS termination, private ingress, or secret management;
- database high availability, backups, or a restore plan; or
- production-safe authentication and database defaults.
For production, use the [supported private-cloud architecture](/self-host/deploy-to-your-cloud/overview) with Kubernetes, Helm, managed MySQL, HTTPS, private networking, managed secrets, and the secure [first-administrator flow](/self-host/deploy-to-your-cloud/first-administrator).