diff --git a/apps/docs/content/docs/core/account-security.mdx b/apps/docs/content/docs/core/account-security.mdx new file mode 100644 index 00000000..a4c93c34 --- /dev/null +++ b/apps/docs/content/docs/core/account-security.mdx @@ -0,0 +1,48 @@ +--- +title: Account Security +description: "Protect your Dokploy account with passkeys (WebAuthn) and two-factor authentication." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +Dokploy supports two mechanisms to secure panel access, and they can be combined: **passkeys** for passwordless sign-in and **two-factor authentication (2FA)** on top of password logins. + +## Passkeys + +Passkeys are a passwordless sign-in method based on WebAuthn. Instead of typing a password (and a 2FA code), you authenticate with your device — Touch ID, Face ID, Windows Hello, or a hardware security key like a YubiKey. The credential never leaves your device and is resistant to phishing: it only works on your Dokploy panel's domain. + +### Registering a passkey + +1. Go to **Settings → Profile**. +2. In the **Passkeys** section, click add and follow your browser's prompt (fingerprint, face, PIN, or security key). +3. Give it a recognizable name — you can register several (e.g. laptop + phone) and remove them individually at any time. + +### Signing in + +On the login page, use the passkey option and pick the credential — no password or 2FA code required. + + + Register at least two passkeys (or keep your password + 2FA working) so losing a device doesn't lock you out. + + +## Two-Factor Authentication (2FA) + +2FA adds a time-based one-time code (TOTP) to password logins, from any authenticator app (Google Authenticator, 1Password, Authy, etc.). + +### Enabling 2FA + +1. Go to **Settings → Profile**. +2. In the **2FA** section, click enable and scan the QR code with your authenticator app. +3. Confirm with a generated code, and store the backup codes somewhere safe — they are the recovery path if you lose the authenticator. + +Once enabled, password sign-ins require the current code from your app. + +## Which one should I use? + +- **Passkeys** are the strongest and most convenient option — phishing-resistant and no codes to type. Prefer them for day-to-day sign-in. +- **2FA** protects the password flow, which remains available as a fallback. If you keep using passwords, enable it. +- Using both gives you a secure fallback chain: passkey for daily use, password + 2FA if a device is unavailable. + + + Organization owners on Dokploy Cloud and self-hosted instances with SSO can additionally enforce sign-in through their identity provider — see the SSO documentation. + diff --git a/apps/docs/content/docs/core/dns-providers/cloudflare.mdx b/apps/docs/content/docs/core/dns-providers/cloudflare.mdx new file mode 100644 index 00000000..ddfc1cf0 --- /dev/null +++ b/apps/docs/content/docs/core/dns-providers/cloudflare.mdx @@ -0,0 +1,32 @@ +--- +title: Cloudflare +description: "Connect Cloudflare to create A/CNAME records for your domains from Dokploy." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## Create an API Token + +1. In the Cloudflare dashboard, go to **My Profile → API Tokens → Create Token**. +2. Use the **Edit zone DNS** template, or create a custom token scoped to **Zone → DNS → Edit**. +3. Under **Zone Resources**, select the zones you want Dokploy to manage — either all zones or specific ones. +4. Create the token and copy it — it is only shown once. + + + Avoid the account-wide Global API Key. Scope the token to Zone → DNS → Edit for only the zones Dokploy needs. + + +## Configuration + +In **Settings → DNS Providers**, add a provider, choose **Cloudflare** and fill in: + +- **Name**: the identifier for this provider, e.g. `cloudflare-main`. +- **API Token**: the token created above. + +Use **Test Connection** to validate the token before saving. + +## Managing Records + +Click **View Domains** on the provider row to list the zones the token can see, then click a zone to view and manage its **A** and **CNAME** records. See [DNS Providers](/docs/core/dns-providers) for the full record form reference. + +Cloudflare's default/automatic TTL is used when the **TTL** field is left empty. diff --git a/apps/docs/content/docs/core/dns-providers/index.mdx b/apps/docs/content/docs/core/dns-providers/index.mdx new file mode 100644 index 00000000..39473a05 --- /dev/null +++ b/apps/docs/content/docs/core/dns-providers/index.mdx @@ -0,0 +1,57 @@ +--- +title: DNS Providers +description: "Connect Cloudflare or AWS Route53 to create and manage A/CNAME records for your domains without leaving Dokploy." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## What are DNS Providers? + +DNS Providers let you connect Dokploy to Cloudflare or AWS Route53 so you can browse your zones and create the **A** or **CNAME** record a domain needs, instead of switching to your DNS provider's dashboard by hand. + + + Enterprise feature. Managing DNS providers is covered by the `dnsProvider` permission resource — grant it granularly with a [custom role](/docs/core/enterprise/custom-roles), or use it as owner/admin. + + +Supported providers: + +- [Cloudflare](/docs/core/dns-providers/cloudflare) +- [AWS Route53](/docs/core/dns-providers/route53) + +## Creating a Provider + +Go to **Settings → DNS Providers** and click to add a provider. Pick **Cloudflare** or **AWS Route53**, give it a name, and fill in the credentials — see the provider pages for exact steps. Use **Test Connection** to validate the credentials before saving. + +Credentials are masked in the UI after saving; leaving a masked field untouched on an edit keeps the stored value. The provider type is locked once created — to switch providers, create a new one. + +## Managing Records + +From the provider list, click **View Domains** to open the zones your credentials can see. Click a zone to expand its records: + +- Records of type **A** and **CNAME** are editable and deletable from Dokploy. +- Other record types (MX, TXT, NS, etc.) returned by the provider are listed read-only. + +To add a record, click **Add Record** and fill in: + +- **Type**: A or CNAME. +- **Name**: the hostname, e.g. `app.example.com`. Use `@` for the zone's root/apex domain. +- **Content**: labeled **IPv4 Address** for A records or **Target** for CNAME records. For A records, an optional **Fill from server** dropdown auto-fills this with the public IP of the Dokploy panel server or any registered remote server. +- **TTL** (optional): leave empty for the provider's automatic/default TTL. + + + Deleting a record from this screen removes it from the actual DNS provider, not just from Dokploy — the confirmation dialog calls this out explicitly. + + +## Relationship to Domains + +DNS Providers is a standalone integration under **Settings**. It is not (yet) wired into the "add domain" flow on applications or Compose services — creating a domain there still expects the DNS record to already point at your server. Use DNS Providers to create that record first (or in parallel), then add the domain in the service as usual. + +## Access Control + +Managing DNS providers is covered by the `dnsProvider` permission resource: + +- **Owners and admins** can create, update, delete and test providers. +- **Members** can read configured providers and zones. +- With an enterprise license, **custom roles** can grant each action (`read`, `create`, `update`, `delete`) granularly. + +Every create, update and delete on a DNS provider is recorded in the [Audit Log](/docs/core/enterprise/audit-logs). diff --git a/apps/docs/content/docs/core/dns-providers/meta.json b/apps/docs/content/docs/core/dns-providers/meta.json new file mode 100644 index 00000000..b7d79c59 --- /dev/null +++ b/apps/docs/content/docs/core/dns-providers/meta.json @@ -0,0 +1,7 @@ +{ + "title": "DNS Providers", + "pages": [ + "cloudflare", + "route53" + ] +} diff --git a/apps/docs/content/docs/core/dns-providers/route53.mdx b/apps/docs/content/docs/core/dns-providers/route53.mdx new file mode 100644 index 00000000..96d297fa --- /dev/null +++ b/apps/docs/content/docs/core/dns-providers/route53.mdx @@ -0,0 +1,48 @@ +--- +title: AWS Route53 +description: "Connect AWS Route53 to create A/CNAME records for your domains from Dokploy." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## Create IAM Credentials + +Create an IAM user (or role) with programmatic access and a least-privilege policy for the hosted zones Dokploy should manage: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "route53:ListHostedZones", + "route53:ListResourceRecordSets", + "route53:ChangeResourceRecordSets" + ], + "Resource": "*" + } + ] +} +``` + +Avoid root account credentials — scope a dedicated IAM user to this policy. + +## Configuration + +In **Settings → DNS Providers**, add a provider, choose **AWS Route53** and fill in: + +- **Name**: the identifier for this provider, e.g. `route53-main`. +- **Access Key ID / Secret Access Key**: the IAM credentials. + +Use **Test Connection** to validate the credentials before saving. + + + Route53 is a global service, so there is no region field — Dokploy talks to it directly. There is also no custom endpoint override: this integration only works against real AWS, not LocalStack or other Route53-compatible emulators. + + +## Managing Records + +Click **View Domains** on the provider row to list your hosted zones, then click a zone to view and manage its **A** and **CNAME** records. See [DNS Providers](/docs/core/dns-providers) for the full record form reference. + +Route53 defaults the **TTL** to `300` seconds when the field is left empty. Since Route53 has no native record ID, renaming a record's name or type is applied as a delete of the old record plus creation of the new one. diff --git a/apps/docs/content/docs/core/enterprise/audit-logs.mdx b/apps/docs/content/docs/core/enterprise/audit-logs.mdx index ea2ce01c..d08f16d4 100644 --- a/apps/docs/content/docs/core/enterprise/audit-logs.mdx +++ b/apps/docs/content/docs/core/enterprise/audit-logs.mdx @@ -35,6 +35,8 @@ Audit Logs track every meaningful action in your organization: - **Infrastructure** — Changes to servers, registries, certificates, SSH keys, and S3 destinations. - **Backups & Schedules** — Creating, updating, or deleting backups, volume backups, and scheduled jobs. - **Notifications** — Changes to notification providers. +- **Secrets Providers** — Creating, updating, or deleting connections to external secret managers (HashiCorp Vault / OpenBao, Infisical, AWS Secrets Manager, Doppler, Azure Key Vault, Scaleway Secret Manager). See [Secrets Providers](/docs/core/secrets-providers). +- **DNS Providers** — Creating, updating, or deleting DNS provider connections (Cloudflare, AWS Route53). See [DNS Providers](/docs/core/dns-providers). ## Filtering diff --git a/apps/docs/content/docs/core/enterprise/custom-roles.mdx b/apps/docs/content/docs/core/enterprise/custom-roles.mdx index 1455de69..230f0df1 100644 --- a/apps/docs/content/docs/core/enterprise/custom-roles.mdx +++ b/apps/docs/content/docs/core/enterprise/custom-roles.mdx @@ -199,6 +199,15 @@ Manage notification providers (Slack, Discord, Telegram, etc.). - **Update** — Modify notification configurations. - **Delete** — Remove notification providers. +### Tags + +Manage tags used to organize and filter projects. + +- **Read** — View tags. +- **Create** — Create new tags. +- **Update** — Edit existing tags. +- **Delete** — Remove tags. + ### Logs View service and deployment logs. @@ -217,6 +226,24 @@ View the audit log of actions performed in the organization. - **Read** — View audit log entries. +### Secrets Providers + +Manage connections to external secret managers (HashiCorp Vault / OpenBao, Infisical, AWS Secrets Manager, Doppler, Azure Key Vault, Scaleway Secret Manager) used to reference secrets in environment variables. See [Secrets Providers](/docs/core/secrets-providers). + +- **Read** — View provider names and secret names (powers the `${{vault.*}}` autocomplete). +- **Create** — Add new secrets providers. +- **Update** — Edit existing provider configuration and assignments. +- **Delete** — Remove secrets providers. + +### DNS Providers + +Manage connections to DNS providers (Cloudflare, AWS Route53) used to automatically create A/CNAME records for domains. See [DNS Providers](/docs/core/dns-providers). + +- **Read** — View configured DNS providers. +- **Create** — Add new DNS providers. +- **Update** — Edit existing DNS provider configuration. +- **Delete** — Remove DNS providers. + ## Creating a Custom Role 1. Go to **Settings → Custom Roles**. diff --git a/apps/docs/content/docs/core/meta.json b/apps/docs/content/docs/core/meta.json index cb8a7eb4..7f85d63e 100644 --- a/apps/docs/content/docs/core/meta.json +++ b/apps/docs/content/docs/core/meta.json @@ -27,8 +27,11 @@ "(S3-Destinations)", "(Git-Sources)", "(Users)", + "account-security", "(Notifications)", "registry", + "secrets-providers", + "dns-providers", "ssh-keys", "certificates", "backups", diff --git a/apps/docs/content/docs/core/secrets-providers/aws.mdx b/apps/docs/content/docs/core/secrets-providers/aws.mdx new file mode 100644 index 00000000..e42dbcf0 --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/aws.mdx @@ -0,0 +1,55 @@ +--- +title: AWS Secrets Manager +description: "Use AWS Secrets Manager secrets in your Dokploy environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## Create IAM Credentials + +Create an IAM user (or use an existing one) with programmatic access and a least-privilege policy for the secrets Dokploy should reach: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["secretsmanager:GetSecretValue", "secretsmanager:ListSecrets"], + "Resource": "arn:aws:secretsmanager:*:*:secret:dokploy/*" + } + ] +} +``` + +`ListSecrets` is only used to power the autocomplete; you can omit it and the provider still resolves references. + +## Configuration + +In **Settings → Secrets → Add Provider**, choose **AWS Secrets Manager** and fill in: + +- **Name**: the identifier used in references, e.g. `aws-sm`. +- **Region**: the region your secrets live in, e.g. `us-east-1`. +- **Access Key ID / Secret Access Key**: the IAM credentials. +- **Endpoint** (optional): a custom endpoint for VPC endpoints or API-compatible emulators (e.g. LocalStack). Leave empty for regular AWS. + +Use **Test Connection** to validate the credentials before saving, then assign the projects/environments where the provider may be used. + +## Reference Format + +References use the secret **name** (not the ARN). Two forms are supported: + +```bash +# Raw SecretString — returns the value exactly as stored +API_TOKEN=${{vault.aws-sm.api-token}} + +# JSON secrets — extract a single field with : +DB_PASSWORD=${{vault.aws-sm.prod/database:password}} +DB_HOST=${{vault.aws-sm.prod/database:host}} +``` + +If the secret stores a JSON object (the common pattern for database credentials), append `:` to pick one key. Without a field, the whole `SecretString` is injected as-is — useful for apps that parse a JSON config blob from a single variable. + + + Binary secrets are not supported — only `SecretString` values. + diff --git a/apps/docs/content/docs/core/secrets-providers/azure.mdx b/apps/docs/content/docs/core/secrets-providers/azure.mdx new file mode 100644 index 00000000..f7ffa0c6 --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/azure.mdx @@ -0,0 +1,49 @@ +--- +title: Azure Key Vault +description: "Use Azure Key Vault secrets in your Dokploy environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +Dokploy authenticates with an **App Registration** (service principal) using the OAuth2 client credentials flow. + +## Create an App Registration + +1. In the Azure Portal, go to **App registrations → New registration**, name it (e.g. `dokploy`) and register it with the defaults — no redirect URI needed. +2. Copy the **Application (client) ID** and the **Directory (tenant) ID** from the overview page. +3. Go to **Certificates & secrets → New client secret** and copy the secret **Value** immediately — it is only shown once. + +## Grant Access to the Vault + +On your Key Vault: + +- **RBAC permission model** (recommended): go to **Access control (IAM) → Add role assignment**, pick the **Key Vault Secrets User** role (read-only) and assign it to the `dokploy` app. +- **Access policies model**: add a policy granting the app `Get` and `List` on secrets. + + + RBAC role assignments can take a few minutes to propagate. If Test Connection fails with a permission error right after assigning the role, wait a moment and retry. + + +## Configuration + +In **Settings → Secrets → Add Provider**, choose **Azure Key Vault** and fill in: + +- **Name**: the identifier used in references, e.g. `azure-kv`. +- **Vault URI**: e.g. `https://my-vault.vault.azure.net`. +- **Tenant ID**: the Directory (tenant) ID. +- **Client ID / Client Secret**: from the App Registration. + +Use **Test Connection** to validate everything before saving, then assign the projects/environments where the provider may be used. + +## Reference Format + +Azure Key Vault secrets are flat values, so references use the secret name directly: + +```bash +DB_PASSWORD=${{vault.azure-kv.db-password}} +STRIPE_KEY=${{vault.azure-kv.stripe-key}} +``` + + + Azure secret names only allow letters, digits and dashes — no underscores. Name your secrets accordingly (e.g. `db-password` instead of `DB_PASSWORD`). + diff --git a/apps/docs/content/docs/core/secrets-providers/doppler.mdx b/apps/docs/content/docs/core/secrets-providers/doppler.mdx new file mode 100644 index 00000000..8ad9b903 --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/doppler.mdx @@ -0,0 +1,41 @@ +--- +title: Doppler +description: "Use Doppler secrets in your Dokploy environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## Create a Token + +The recommended token type is a **Service Token** (`dp.st.`): it is read-only and scoped to a single project + config, so a leaked token only exposes that config. + +1. In Doppler, open your **project → config** (e.g. `prd`). +2. Go to the **Access** tab and click **Generate Service Token**. +3. Copy the token. + +Personal (`dp.pt.`) and CLI (`dp.ct.`) tokens also work, but since they are not bound to a config you must additionally fill in the **Project** and **Config** fields. + +## Configuration + +In **Settings → Secrets → Add Provider**, choose **Doppler** and fill in: + +- **Name**: the identifier used in references, e.g. `doppler-prd`. +- **Token**: the Doppler token. +- **Project / Config** (optional): only required for personal/CLI tokens — service tokens already carry them. + +Use **Test Connection** to validate the token before saving, then assign the projects/environments where the provider may be used. + + + A provider points at a single Doppler config. For several configs (e.g. `dev` and `prd`), create one provider per config and assign each one to the matching Dokploy environments. + + +## Reference Format + +Doppler secrets are flat key/value pairs within the config, so references use the secret name directly: + +```bash +DATABASE_URL=${{vault.doppler-prd.DATABASE_URL}} +STRIPE_KEY=${{vault.doppler-prd.STRIPE_KEY}} +``` + +The autocomplete lists the real secret names of the configured Doppler config. diff --git a/apps/docs/content/docs/core/secrets-providers/hashicorp.mdx b/apps/docs/content/docs/core/secrets-providers/hashicorp.mdx new file mode 100644 index 00000000..eca46ed2 --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/hashicorp.mdx @@ -0,0 +1,61 @@ +--- +title: HashiCorp Vault / OpenBao +description: "Use HashiCorp Vault or OpenBao KV v2 secrets in your Dokploy environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +Dokploy talks to the KV version 2 secrets engine. The same provider works with **HashiCorp Vault** and **[OpenBao](https://openbao.org)** (the open-source fork) — their APIs are identical. + +## Configuration + +In **Settings → Secrets → Add Provider**, choose **HashiCorp Vault / OpenBao** and fill in: + +- **Name**: the identifier used in references, e.g. `prod-vault`. +- **Vault URL**: the address of your Vault/OpenBao server, e.g. `https://vault.example.com:8200`. It must be reachable from your Dokploy server. +- **Token**: a Vault token with `read` (and `list`, for autocomplete) capabilities on the secrets you want to expose. +- **KV Mount**: the mount path of the KV v2 engine. Defaults to `secret`. +- **Namespace** (optional): for Vault Enterprise or OpenBao namespaces, e.g. `admin`. + +Use **Test Connection** to validate the token before saving, then assign the projects/environments where the provider may be used. + + + Create a token from a policy that only grants read/list on the paths Dokploy needs, for example: + +```hcl +path "secret/data/myapp/*" { + capabilities = ["read"] +} +path "secret/metadata/*" { + capabilities = ["list"] +} +``` + + +## Reference Format + +KV v2 secrets are maps of fields, so references always include the path **and** the field, separated by a colon: + +```bash +DB_PASSWORD=${{vault.prod-vault.myapp/prod:DB_PASSWORD}} +API_KEY=${{vault.prod-vault.shared:API_KEY}} +``` + +`myapp/prod` is the secret path inside the KV mount and `DB_PASSWORD` is the field inside that secret. The autocomplete walks your KV tree and suggests complete `path:field` references. + +## Trying it with OpenBao + +For a quick local test, OpenBao's dev mode gives you a ready-to-use server: + +```bash +docker run -d --name openbao -p 8200:8200 \ + -e BAO_DEV_ROOT_TOKEN_ID=dev-token \ + -e BAO_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \ + openbao/openbao:latest +``` + +Then create the provider with URL `http://:8200`, token `dev-token` and mount `secret`. + + + Dev mode stores everything in memory and is for testing only. + diff --git a/apps/docs/content/docs/core/secrets-providers/index.mdx b/apps/docs/content/docs/core/secrets-providers/index.mdx new file mode 100644 index 00000000..18d194ea --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/index.mdx @@ -0,0 +1,106 @@ +--- +title: Secrets Providers +description: "Reference secrets from external secret managers (HashiCorp Vault, OpenBao, Infisical, AWS Secrets Manager, Doppler, Azure Key Vault, Scaleway Secret Manager) directly in your environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## What are Secrets Providers? + +Secrets Providers let you connect Dokploy to an external secret manager and reference its secrets from any environment variable editor: + +```bash +DATABASE_URL=${{vault.prod-vault.myapp/creds:DB_URL}} +API_KEY=${{vault.doppler-prod.API_KEY}} +``` + +Secrets are fetched from the provider **at deploy time** and injected into the prepared environment. The values are never stored in the Dokploy database — your vault remains the single source of truth, and what members see in the env editor is the reference, not the value. + + + Available from **v0.30.0**. + + +Supported providers: + +- [HashiCorp Vault / OpenBao](/docs/core/secrets-providers/hashicorp) +- [Infisical](/docs/core/secrets-providers/infisical) +- [AWS Secrets Manager](/docs/core/secrets-providers/aws) +- [Doppler](/docs/core/secrets-providers/doppler) +- [Azure Key Vault](/docs/core/secrets-providers/azure) +- [Scaleway Secret Manager](/docs/core/secrets-providers/scaleway) + +## Reference Syntax + +``` +${{vault..}} +``` + +- `` — the name you gave the provider when creating it. It is unique per organization and can only contain letters, numbers, dashes and underscores. +- `` — provider-specific: + +| Provider | Ref format | Example | +|---|---|---| +| HashiCorp Vault / OpenBao | `:` | `myapp/prod:DB_PASSWORD` | +| Infisical | `` | `DB_PASSWORD` | +| AWS Secrets Manager | `` or `:` | `prod/myapp:password` | +| Doppler | `` | `DB_PASSWORD` | +| Azure Key Vault | `` | `db-password` | +| Scaleway Secret Manager | `[folder/][:field]` | `prod/database:password` | + +References work in every place that flows into a deployment: + +- Service environment variables (applications, Docker Compose, databases) +- Project-level shared variables +- Environment-level shared variables +- Build-time arguments and build secrets + +They resolve **before** `${{project.X}}` and `${{environment.X}}` interpolation, so both compose naturally: + +```bash +# Environment-level shared variable +DB_PASSWORD=${{vault.prod-vault.myapp/prod:DB_PASSWORD}} + +# Service variable consuming it +DATABASE_URL=postgres://app:${{environment.DB_PASSWORD}}@db:5432/app +``` + +You don't need to remember the syntax: the environment editors autocomplete it. Type `${{` and the editor suggests `project.`, `environment.` and `vault.`; picking `vault.` lists your providers, and picking a provider lists the real secret names fetched from it. + +## Creating a Provider + +Go to **Settings → Secrets** and click **Add Provider**. Each provider type has its own form — see the provider pages for step-by-step credentials setup. Every form includes a **Test Connection** button that validates the credentials before saving. + +Credentials are masked in every API response and in the UI after saving; when editing a provider, leaving a masked field untouched keeps the stored value. + +## Access Control + +Two independent layers control secrets providers: + +### Project and environment assignments + +Each provider carries an explicit **assignment list** that defines where it can be used. In the provider form, select the projects that may reference it; for each selected project you can optionally narrow it down to specific environments. + +- Selecting a project with **no environments** enables the provider in **all** environments of that project (including ones created later). +- Selecting specific environments enables it **only** there — for example, a `prod-vault` provider assigned only to the `production` environment cannot be referenced from `development`. +- A provider with **no assignments** is enabled nowhere until you assign it. + +Enforcement happens on the server before any request reaches your vault: a reference to a provider that is not enabled for the deploying project/environment fails the deployment with a clear error, and the autocomplete only suggests providers enabled for the editor you are typing in. + + + Project-level shared variables are evaluated by every environment of the project. If you reference an environment-restricted provider from a project-level variable, deployments in the other environments will fail. Put references to restricted providers in the environment-level or service-level variables instead. + + +### Role permissions + +Managing providers is covered by the `vaultProvider` permission resource: + +- **Owners and admins** can create, update, delete and test providers. +- **Members** can read provider names and secret names — this is what powers the autocomplete. They never see credentials or secret values. +- With an enterprise license, **custom roles** can grant each action (`read`, `create`, `update`, `delete`) granularly. + +## Security Model + +- **Values never touch the Dokploy database or the UI.** Members with access to a service see `${{vault.prod-vault.DB_URL}}` in the editor, not the value. +- **Rotation requires a redeploy.** Values are fetched at deploy time, so rotating a secret in your vault takes effect on the next deployment. +- **Use least-privilege credentials on the vault side.** Whoever can edit environment variables and deploy in an assigned project can read what the provider's token reaches there — the same trust model as any CI/CD system. Scope the token per environment where your provider supports it (Doppler service tokens, Vault policies, Infisical machine identities). +- A deleted or missing secret fails the deployment with an explicit error instead of injecting an empty value. diff --git a/apps/docs/content/docs/core/secrets-providers/infisical.mdx b/apps/docs/content/docs/core/secrets-providers/infisical.mdx new file mode 100644 index 00000000..2f8d033a --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/infisical.mdx @@ -0,0 +1,46 @@ +--- +title: Infisical +description: "Use Infisical secrets (cloud or self-hosted) in your Dokploy environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +Dokploy authenticates against Infisical with a **Machine Identity** using Universal Auth — the method Infisical recommends for programmatic access. Both Infisical Cloud and self-hosted instances are supported. + +## Create a Machine Identity + +1. In Infisical, go to your **Organization → Access Control → Identities** and create a new identity, e.g. `dokploy`. +2. Add the **Universal Auth** method to it and create a **Client Secret**. Copy the **Client ID** and the **Client Secret**. +3. Add the identity to the project you want to expose, with a role that can read secrets. + +## Configuration + +In **Settings → Secrets → Add Provider**, choose **Infisical** and fill in: + +- **Name**: the identifier used in references, e.g. `infisical-prod`. +- **Site URL**: `https://app.infisical.com` for Infisical Cloud, or the URL of your self-hosted instance. +- **Client ID / Client Secret**: from the Universal Auth method of your machine identity. +- **Project ID**: the Infisical project to read from (visible in the project settings). +- **Environment**: the Infisical environment slug, e.g. `dev`, `staging` or `prod`. +- **Secret Path**: defaults to `/`. + +Use **Test Connection** to validate everything before saving, then assign the Dokploy projects/environments where the provider may be used. + + + A provider points at a single Infisical project + environment. To use several Infisical environments, create one provider per environment (e.g. `infisical-dev`, `infisical-prod`) and assign each one to the matching Dokploy environments. + + +## Reference Format + +Infisical secrets are flat key/value pairs within the configured project + environment, so references use the secret name directly: + +```bash +DB_PASSWORD=${{vault.infisical-prod.DB_PASSWORD}} +STRIPE_KEY=${{vault.infisical-prod.STRIPE_KEY}} +``` + +The autocomplete lists the real secret names of the configured environment. + + + You can run Infisical itself on Dokploy — it is available as a template — and point the provider at it. + diff --git a/apps/docs/content/docs/core/secrets-providers/meta.json b/apps/docs/content/docs/core/secrets-providers/meta.json new file mode 100644 index 00000000..47eb50d0 --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Secrets Providers", + "pages": [ + "hashicorp", + "infisical", + "aws", + "doppler", + "azure", + "scaleway" + ] +} diff --git a/apps/docs/content/docs/core/secrets-providers/scaleway.mdx b/apps/docs/content/docs/core/secrets-providers/scaleway.mdx new file mode 100644 index 00000000..b207693c --- /dev/null +++ b/apps/docs/content/docs/core/secrets-providers/scaleway.mdx @@ -0,0 +1,49 @@ +--- +title: Scaleway Secret Manager +description: "Use Scaleway Secret Manager secrets in your Dokploy environment variables." +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## Create an API Key + +Dokploy authenticates with a Scaleway **API key** scoped to the project your secrets live in. + +1. In the Scaleway console, go to **IAM → API Keys → Generate an API key**. +2. Scope it to the project that holds your secrets, and attach a permission set that includes **SecretManagerReadOnly** (or a policy with equivalent read access). +3. Copy the **Secret Key** — like other Scaleway API keys, it is only shown once. + + + The Secret Key is the credential, there is no separate access key ID — Dokploy authenticates with it alone via the `X-Auth-Token` header. + + +## Configuration + +In **Settings → Secrets → Add Provider**, choose **Scaleway Secret Manager** and fill in: + +- **Name**: the identifier used in references, e.g. `scaleway-sm`. +- **Region**: the region your secrets live in — `fr-par`, `nl-ams` or `pl-waw`. +- **Project ID**: the Scaleway project holding the secrets. +- **Secret Key**: the API key's secret key. +- **API URL** (optional): defaults to `https://api.scaleway.com`. Override only for API-compatible proxies/emulators. + +Use **Test Connection** to validate the credentials before saving, then assign the projects/environments where the provider may be used. + +## Reference Format + +References use the secret **name**, optionally prefixed with its folder path, and optionally suffixed with `:` to extract a key from a JSON payload: + +```bash +# Secret at the root +API_TOKEN=${{vault.scaleway-sm.api-token}} + +# Secret inside a folder +DB_PASSWORD=${{vault.scaleway-sm.prod/database:password}} +DB_HOST=${{vault.scaleway-sm.prod/database:host}} +``` + +If the secret's latest enabled version stores a JSON object, append `:` to pick one key. Without a field, the whole payload is injected as-is. + + + Only the **latest enabled version** of a secret is read. + diff --git a/apps/docs/content/docs/core/variables.mdx b/apps/docs/content/docs/core/variables.mdx index 1f29254f..0de32458 100644 --- a/apps/docs/content/docs/core/variables.mdx +++ b/apps/docs/content/docs/core/variables.mdx @@ -105,6 +105,16 @@ DATABASE_URL=postgresql://${{DATABASE_USER}}:${{DATABASE_PASSWORD}}@service-data It can be used as `${{DOKPLOY_DEPLOY_URL}}` for variables like `APP_URL=https://${{DOKPLOY_DEPLOY_URL}}`. +## Secrets from External Vaults + +Besides shared variables, you can reference secrets stored in an external secret manager (HashiCorp Vault/OpenBao, Infisical, AWS Secrets Manager, Doppler, Azure Key Vault): + +```bash +DB_PASSWORD=${{vault.prod-vault.myapp/prod:DB_PASSWORD}} +``` + +Values are fetched at deploy time and never stored in Dokploy. See [Secrets Providers](/docs/core/secrets-providers) for setup, reference formats and access control. + ### Best Practices - Use shared variables for credentials and configurations that repeat across services