diff --git a/astro.config.mjs b/astro.config.mjs index d359ddd3..3b2440b3 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -14,12 +14,12 @@ export default defineConfig({ site, trailingSlash: 'never', publicDir: './static', + server: { host: true }, build: { format: 'file' }, image: { remotePatterns: [ { protocol: 'https', hostname: 'i.ytimg.com' }, - { protocol: 'https', hostname: 'miro.medium.com' }, - { protocol: 'https', hostname: 'www.virtualizationhowto.com' } + { protocol: 'https', hostname: 'miro.medium.com' } ] }, vite: { diff --git a/src/assets/community/virtualizationhowto-docker-ui.webp b/src/assets/community/virtualizationhowto-docker-ui.webp new file mode 100644 index 00000000..48c5191e Binary files /dev/null and b/src/assets/community/virtualizationhowto-docker-ui.webp differ diff --git a/src/components/community/CommunityCard.astro b/src/components/community/CommunityCard.astro index b958bc60..13b50256 100644 --- a/src/components/community/CommunityCard.astro +++ b/src/components/community/CommunityCard.astro @@ -9,6 +9,12 @@ interface Props { } const { item } = Astro.props; +// Remote thumbnails need their size fetched at build time; imported assets already carry it. +const thumbnail = + typeof item.thumbnail === 'string' + ? { src: item.thumbnail, inferSize: true as const } + : item.thumbnail && { src: item.thumbnail }; + const formatDate = (isoDate: string) => { const date = new Date(`${isoDate}T00:00:00Z`); if (Number.isNaN(date.getTime())) return isoDate; @@ -56,11 +62,10 @@ const badge =
- {item.thumbnail ? ( + {thumbnail ? ( [!IMPORTANT] > **Updates → Update All** updates your containers and projects. **Environments → Update All** upgrades Arcane managers and agents; see [Remote Environments](/docs/remote/environments). If Arcane's own container has a pending update, **Updates → Update All** includes it and restarts Arcane after the other updates finish. The confirmation tells you when this applies. diff --git a/src/content/docs/docs/docker/backups.mdx b/src/content/docs/docs/docker/backups.mdx index c4f47050..93814e01 100644 --- a/src/content/docs/docs/docker/backups.mdx +++ b/src/content/docs/docs/docker/backups.mdx @@ -117,6 +117,8 @@ Retention runs separately for each schedule, and separately for local and S3 cop Deleting backups by hand also tries to remove every stored copy. If the local copy is deleted but S3 deletion fails, the row stays as S3-only and Arcane reports the error. If any remote copy can't be deleted, the row stays, so the backup isn't wrongly shown as gone. +Deleting a local backup doesn't free its disk space right away. Arcane prunes the local system and volume backup repositories at 04:15 and 16:15 every day in Arcane's configured timezone, and Rustic keeps deleted data for about a day before a prune removes it, so the space can take up to two days to come back. + ### System-managed volume backups To back up many volumes with one schedule, an admin can open **Settings → Backups**, click **Create schedule**, and choose the **Volume** type. Set the schedule, retention, destination, and stop-containers option as above, then pick which volumes to include: diff --git a/src/content/docs/docs/docker/containers.mdx b/src/content/docs/docs/docker/containers.mdx index c900831c..4602233f 100644 --- a/src/content/docs/docs/docker/containers.mdx +++ b/src/content/docs/docs/docker/containers.mdx @@ -91,6 +91,10 @@ The **Overview** tab's **Auto Update** toggle turns automatic installation on or When a newer image is available, the detail header shows an **Update available** badge and an **Update** action to apply it on the spot (requires the `containers:autoupdate` permission). If the container belongs to a project, the header links to that project too. +## Open a shell + +With `containers:exec`, a running container's detail view has a **Shell** tab. Pick `sh`, `bash`, `ash`, `zsh`, or a custom path. Your browser remembers the choice per Compose service, or per container name for standalone containers, so it survives recreating the container. Otherwise the tab uses the environment's **Default Shell** (**Environments → the environment → Docker**), `/bin/sh` by default. + ## View logs Open a container's detail view and switch to the **Logs** tab. The viewer: diff --git a/src/content/docs/docs/docker/projects.mdx b/src/content/docs/docs/docker/projects.mdx index e434911d..8b5ca4de 100644 --- a/src/content/docs/docs/docker/projects.mdx +++ b/src/content/docs/docs/docker/projects.mdx @@ -33,7 +33,9 @@ Use the **Labels** filter to find projects with a container label. Enter a key s 2. Enter a name. 3. Paste or write the Compose YAML. 4. Optional: open the **Environment Configuration (.env)** editor and add variables. Arcane saves them to a `.env` file next to the Compose file. -5. Click **Create Project**. Arcane saves the project and tries to start it. +5. Click **Create Project**, or press `Ctrl/Cmd+S`. Arcane saves the project and tries to start it. + +Arcane creates the project folder from the name. If the Projects Directory already has a folder with that name that contains no Compose file and isn't used by another project, Arcane creates the project in it and keeps the files already there. An existing `.env` is kept if you leave the `.env` editor empty; different content is rejected. Otherwise Arcane adds a number to the folder name, such as `myapp-1`. ## Control a project @@ -82,7 +84,7 @@ From the workspace panel you can: - **Edit**: open any UTF-8 text file in its own tab. Binary files can be uploaded but not edited. - **Rename**, **Move**, and **Delete**: reorganize the folder. Non-empty folders can be deleted recursively. -All file changes are staged until you **Save** the project. Build and dependency folders (`.git`, `node_modules`, `vendor`, `dist`, `build`, and similar) are hidden from the tree. For projects using Git **Pull**, files managed by the sync are read-only; other workspace files stay editable. +All file changes are staged until you **Save** the project or press `Ctrl/Cmd+S`. Middle-click a tab to close it. Build and dependency folders (`.git`, `node_modules`, `vendor`, `dist`, `build`, and similar) are hidden from the tree. For projects using Git **Pull**, files managed by the sync are read-only; other workspace files stay editable. > [!NOTE] > The Compose file, `.env`, `.env.git`, and `project.env` are protected. They show a lock icon and can't be renamed, moved, or deleted from the tree. Edit them through their own editors instead. diff --git a/src/content/docs/docs/docker/template-registries.md b/src/content/docs/docs/docker/template-registries.md index 7ca7e681..871895d8 100644 --- a/src/content/docs/docs/docker/template-registries.md +++ b/src/content/docs/docs/docker/template-registries.md @@ -46,6 +46,7 @@ Include `$schema` so editors can validate the file: "compose_url": "https://raw.githubusercontent.com/yourcompany/docker-templates/main/internal-app/docker-compose.yml", "env_url": "https://raw.githubusercontent.com/yourcompany/docker-templates/main/internal-app/.env.example", "documentation_url": "https://github.com/yourcompany/docker-templates/tree/main/internal-app", + "icon_url": "https://raw.githubusercontent.com/yourcompany/docker-templates/main/internal-app/icon.svg", "tags": ["internal", "webapp", "postgres"] } ] @@ -92,7 +93,7 @@ The registry must match the schema at `https://github.com/getarcaneapp/arcane-te ### Template fields -All template fields are required. +All template fields are required except `icon_url`. | Field | Description | | ------------------- | --------------------------------------------------------- | @@ -104,4 +105,7 @@ All template fields are required. | `compose_url` | Direct URL to the Compose file. | | `env_url` | Direct URL to the `.env.example` file. | | `documentation_url` | URL to the template's docs or README. | +| `icon_url` | Direct URL to the template's icon. | | `tags` | Array of unique slugs (lowercase, hyphens), at least one. | + +Arcane shows `icon_url` for remote templates and doesn't read icons from their Compose files. After you **Download** a template, an `x-arcane` icon in its Compose file takes precedence. diff --git a/src/content/docs/docs/get-started/preview-builds.mdx b/src/content/docs/docs/get-started/preview-builds.mdx index 8d571f32..3fad2cc7 100644 --- a/src/content/docs/docs/get-started/preview-builds.mdx +++ b/src/content/docs/docs/get-started/preview-builds.mdx @@ -50,6 +50,10 @@ volumes: > [!TIP] > To stay on one build instead of following `next`, use its versioned tag, for example `ghcr.io/getarcaneapp/manager:v2.4.0-next.1`. +## Development branding + +Preview builds, and any other build whose version isn't a plain release such as `v2.4.0`, use a development icon in place of the Arcane logo, favicon, and app icons. To show the standard logo instead, click the version number at the bottom of the sidebar and switch off **Development Branding** (requires `settings:write`). + ## Download a binary diff --git a/src/content/docs/docs/get-started/preview-features.mdx b/src/content/docs/docs/get-started/preview-features.mdx new file mode 100644 index 00000000..cb035148 --- /dev/null +++ b/src/content/docs/docs/get-started/preview-features.mdx @@ -0,0 +1,78 @@ +--- +title: 'Preview Features' +description: 'Turn on features that are still in development in the web UI, iOS app, and CLI.' +--- + +import { Badge, TabItem, Tabs } from '@astrojs/starlight/components'; + +Preview features are still in development. They are off by default, and you turn each one on separately in the web UI, the iOS app, or the CLI. They may not work as expected, and their behavior may change or be removed in a later release. + +## All environments + + + +The all environments preview replaces the environment switcher with one combined view. Resource lists such as containers, projects, images, volumes, networks, ports, updates, and vulnerability scans show items from every enabled environment together, with each item labeled by the environment it belongs to. Actions on a resource run in that resource's environment. + +The preview is turned on separately in each client. Turning it on in the web UI doesn't change the iOS app or the CLI. + +### Turn on all environments + + + + + +1. Click your avatar at the bottom of the sidebar and select **Account**. +2. Open the **Previews** tab. +3. Switch on **All environments (preview)**. + +The setting is saved to your user account, so it follows you to any browser you sign in from. While the preview is on, the **Previews** tab also offers: + +- **Environment labels**: show the environment's name in resource lists, or only a color dot with the name on hover. +- **Environment colors**: pick a color for each environment's label. + +To turn the preview off, switch it off on the **Previews** tab, or open the environment switcher and click **Turn off preview**. + + + + + +1. Open the **More** tab and select **Preview Features**. +2. Switch on **All Environments**. + +You can also turn it on from the walkthrough: tap **Replay Walkthrough** on the same screen and tap **Enable Preview** on the last page. **Environment Colors** sets the color shown next to each environment's resources. + +The setting is stored on the device. Environment switching is hidden while the preview is on; switch **All Environments** off to choose a single environment again. + + + + + +Set `previews.allEnvironments` in your [CLI config](/docs/reference/cli/config): + +```bash +arcane-cli config set previews.allEnvironments true +arcane-cli containers list +``` + +Lists use one combined table with an `ENVIRONMENT` column. To run a single command against one environment, pass `--env `. To turn the preview off and return to your saved default environment: + +```bash +arcane-cli config set previews.allEnvironments false +``` + +See [Preview every environment](/docs/reference/cli/config#preview-every-environment) for resource pickers, fleet confirmations, and the aggregate JSON format. + + + + + +### What changes while it's on + +- **Only enabled environments are included.** Disabled environments don't appear. If an environment can't be reached, the rest still load and a notice lists the ones that are missing. +- **Environment switching is unavailable.** The combined view replaces picking a single environment. Use list filters to focus on one environment without leaving the view. +- **Bulk actions apply to every environment.** Update checks, updates, and pruning run on all enabled environments, even when a list is filtered. The confirmation shows how many environments the action will run on, so review it before you continue. +- **Global pages work as before.** Pages that aren't tied to one environment, such as users, registries, templates, and variables, keep their existing scope. + +## Report a problem + +Report problems with preview features on [GitHub Issues](https://github.com/getarcaneapp/arcane/issues). Include which client you were using and the version shown on your dashboard. diff --git a/src/content/docs/docs/networking/reverse-proxy.mdx b/src/content/docs/docs/networking/reverse-proxy.mdx index fd1ce04a..72d099fb 100644 --- a/src/content/docs/docs/networking/reverse-proxy.mdx +++ b/src/content/docs/docs/networking/reverse-proxy.mdx @@ -180,13 +180,13 @@ A working setup logs `Edge tunnel connected to manager` with `transport=grpc`. I Arcane rate-limits authentication endpoints (login, token refresh, OIDC callback) per client IP. Behind a reverse proxy, every request appears to come from the proxy's IP. That weakens brute-force protection and can lock out legitimate users who share the proxy. -Set `TRUSTED_PROXIES` on the Arcane container to your proxy's address, such as `TRUSTED_PROXIES=10.0.0.5`, or to a CIDR range, such as the Docker network that the proxy and Arcane share (`TRUSTED_PROXIES=172.18.0.0/16`). Arcane then reads the real client IP from `X-Forwarded-For` for requests coming from those addresses. Docker's default address pools hand out subnets from `172.17.0.0`–`172.31.0.0` and then `192.168.0.0/16`, and your daemon may be configured differently, so look up the network's actual subnet: +Set `TRUSTED_PROXIES` on the Arcane container to your proxy's address, such as `TRUSTED_PROXIES=10.0.0.5/32`, or to a wider CIDR range, such as the Docker network that the proxy and Arcane share (`TRUSTED_PROXIES=172.18.0.0/16`). Arcane then reads the real client IP from `X-Forwarded-For` for requests coming from those addresses. Docker's default address pools hand out subnets from `172.17.0.0`–`172.31.0.0` and then `192.168.0.0/16`, and your daemon may be configured differently, so look up the network's actual subnet: ```bash docker network inspect --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' ``` -`TRUSTED_PROXIES` accepts a comma-separated list of IPs or CIDR ranges. Only requests whose direct peer is in this list have their forwarded headers trusted, so an untrusted client cannot spoof its IP via `X-Forwarded-For`. See the [Environment Variables](/docs/reference/environment-variables) reference for all configuration options. +`TRUSTED_PROXIES` accepts a comma-separated list of CIDR ranges. Write a single address as `/32` for IPv4 or `/128` for IPv6; Arcane logs a warning and ignores entries without a prefix length. Only requests whose direct peer is in this list have their forwarded headers trusted, so an untrusted client cannot spoof its IP via `X-Forwarded-For`. Loopback and private-network addresses are not trusted unless they are in the list. See the [Environment Variables](/docs/reference/environment-variables) reference for all configuration options. > [!NOTE] > If you bind Arcane to a loopback address with `LISTEN`, such as `LISTEN=127.0.0.1` for a proxy on the same host, Arcane trusts loopback proxies (`127.0.0.0/8`, `::1/128`) automatically and you don't need `TRUSTED_PROXIES`. This only works with literal loopback IPs, not hostnames such as `localhost`. diff --git a/src/content/docs/docs/reference/cli/commands.md b/src/content/docs/docs/reference/cli/commands.md index a64ddda1..0b3b1833 100644 --- a/src/content/docs/docs/reference/cli/commands.md +++ b/src/content/docs/docs/reference/cli/commands.md @@ -275,6 +275,8 @@ Switch between the stable and next release channels: arcane-cli self-update channel next ``` +To check release signatures before updating, turn on the [signature verification preview](/docs/reference/cli/config#verify-self-update-signatures). + ## Diagnose problems and set up your shell Diagnose connectivity and configuration problems: @@ -300,10 +302,15 @@ arcane-cli generate secret Every command accepts `--output json` (or the shorthand `--json`), which makes the CLI easy to pair with `jq`: ```bash -arcane-cli containers list --json | jq -r ".[].name" +arcane-cli containers list --json | jq -r ".data[].name" ``` -Add `--yes` to skip confirmation prompts in unattended scripts. +In JSON mode, stdout carries exactly one JSON document. Status messages and progress go to stderr. List commands print the server's paginated response with `data` and `pagination`. Other commands print only the resource or result. `images pull`, `images build`, and the streaming `projects` commands print an array of the server's progress frames once the operation finishes. + +Commands that remove or reset resources ask for confirmation first. Add `--yes` to skip confirmation prompts in unattended scripts. On delete commands, `--force` skips the prompt too. + +> [!IMPORTANT] +> Without a terminal, or with `--json`, a prompt fails with `confirmation required: re-run with --yes` instead of waiting for input. Piping `y` into the command does not answer it. List commands are paginated. `--all` (`-a`) returns every item, ignoring pagination — it cannot be combined with `--limit` or `--start`: @@ -313,3 +320,14 @@ arcane-cli containers list --all --json > [!NOTE] > `--all` means "ignore pagination", not "include stopped containers". `containers list` already returns containers in every state. + +## Renamed flags + +Some flags were renamed so they no longer clash with the global `--env`, `--config`, and `--output` flags, or to replace a separate off switch. The old names still work but print a deprecation warning, and they will be removed in v3. Update your scripts to the new names: + +| Command | Old flag | New flag | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------- | +| `containers create` | `--env` | `--env-var`, `-e` | +| `admin notifications settings set` | `--config` | `--provider-config` | +| `templates download` | `--output` | `--output-file`, `-o` | +| `environments create`, `environments update`, `registries create`, `registries update`, `templates registries update`, `admin federated update`, `admin backups policies update` | `--disabled` | `--enabled=false` | diff --git a/src/content/docs/docs/reference/cli/config.md b/src/content/docs/docs/reference/cli/config.md deleted file mode 100644 index 38a37fde..00000000 --- a/src/content/docs/docs/reference/cli/config.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: 'CLI Configuration' -description: 'Point arcane-cli at your server, sign in, and set defaults.' ---- - -`arcane-cli` keeps its server URL, credentials, and defaults in a YAML config file. Set it up once after you [install the CLI](/docs/reference/cli/install), and change values later with `arcane-cli config set `. - -## Set up the CLI - -1. Create a starter config file: - -```bash -arcane-cli config init -``` - -2. Set your server URL: - -```bash -arcane-cli config set server-url http://localhost:3552 -``` - -3. Sign in with one of the methods below. - -## Sign in - -### With a device code - -Use this when your Arcane server has OIDC set up and you want to sign in through your identity provider in a browser. - -```bash -arcane-cli auth login -``` - -Device-code login can't complete an MFA challenge. If your account has passkey MFA turned on, use an API key instead. See [Passkeys & MFA](/docs/access/passkeys). - -### With an API key - -Use this for CI/CD, automation, or accounts with MFA. - -```bash -arcane-cli config set api-key arc_xxxxxxx -``` - -## Change list limits - -List commands are paginated. The page size is chosen in this order: - -1. `--limit` on the command -2. `pagination.resources..limit` in the config -3. `pagination.default.limit` in the config -4. The command's built-in default - -Set limits from the CLI: - -```bash -arcane-cli config set default-limit 25 -``` - -```bash -arcane-cli config set pagination.resources.containers.limit 50 pagination.resources.images.limit 100 -``` - -You can also edit `pagination` in the config file directly (see the example below). The resource names are `containers`, `images`, `volumes`, `networks`, `projects`, `environments`, `registries`, `templates`, `repos`, `gitops-syncs`, `users`, `roles`, `events`, and `apikeys`. - -For `doctor`, shell completion, and other commands, see [CLI Commands](/docs/reference/cli/commands). - -## Reference - -### Config file - -The config file is at `~/.config/arcanecli.yml` by default. Print the exact path on your system with: - -```bash -arcane-cli config path -``` - -A typical config file: - -```yaml -api_key: '' -cli_update_channel: stable -default_environment: '0' -federated_audience: '' -jwt_token: '' -log_level: info -pagination: - default: - limit: 20 - resources: - containers: - limit: 50 - images: - limit: 100 -refresh_token: '' -server_url: http://localhost:3552 -``` - -### Global flags - -These flags work on every command. - -| Flag | Purpose | -| ------------------------------ | ------------------------------------------------------------------------ | -| `--output ` | Output mode, `text` or `json`. `--json` is an alias for `--output json`. | -| `--env ` | Use a different environment than the configured default for one command. | -| `--yes` | Auto-confirm destructive prompts. | -| `--no-color` | Disable ANSI color output. | -| `--request-timeout ` | Override the HTTP timeout for one command. | -| `--config`, `-c ` | Use a config file other than the default. | -| `--log-level ` | Set verbosity: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. | -| `--log-json` | Emit structured JSON logs. | diff --git a/src/content/docs/docs/reference/cli/config.mdx b/src/content/docs/docs/reference/cli/config.mdx new file mode 100644 index 00000000..8af2ea9f --- /dev/null +++ b/src/content/docs/docs/reference/cli/config.mdx @@ -0,0 +1,230 @@ +--- +title: 'CLI Configuration' +description: 'Point arcane-cli at your server, sign in, and set defaults.' +--- + +import { Badge } from '@astrojs/starlight/components'; + +`arcane-cli` keeps its server URL, credentials, and defaults in a YAML config file. Set it up once after you [install the CLI](/docs/reference/cli/install), and change values later with `arcane-cli config set `. + +## Set up the CLI + +1. Create a starter config file: + +```bash +arcane-cli config init +``` + +2. Set your server URL: + +```bash +arcane-cli config set server-url http://localhost:3552 +``` + +3. Sign in with one of the methods below. + +## Sign in + +### With a device code + +Use this when your Arcane server has OIDC set up and you want to sign in through your identity provider in a browser. + +```bash +arcane-cli auth login +``` + +The CLI saves the session to `~/.arcanecli/auth.json`, not the config file. See [Auth file](#auth-file). + +Device-code login can't complete an MFA challenge. If your account has passkey MFA turned on, use an API key instead. See [Passkeys & MFA](/docs/access/passkeys). + +### With an API key + +Use this for CI/CD, automation, or accounts with MFA. + +```bash +arcane-cli config set api-key arc_xxxxxxx +``` + +## Change list limits + +List commands are paginated. The page size is chosen in this order: + +1. `--limit` on the command +2. `pagination.resources..limit` in the config +3. `pagination.default.limit` in the config +4. The command's built-in default + +Set limits from the CLI: + +```bash +arcane-cli config set default-limit 25 +``` + +```bash +arcane-cli config set pagination.resources.containers.limit 50 pagination.resources.images.limit 100 +``` + +You can also edit `pagination` in the config file directly (see the example below). The resource names are `containers`, `images`, `volumes`, `networks`, `projects`, `environments`, `registries`, `templates`, `repos`, `gitops-syncs`, `users`, `roles`, `events`, and `apikeys`. + +For `doctor`, shell completion, and other commands, see [CLI Commands](/docs/reference/cli/commands). + +## Preview every environment + + + +> [!IMPORTANT] +> All-environments mode is a preview feature. Its behavior, output, and JSON format are subject to change at any time. + +Enable all-environments preview to list resources and perform actions without setting a default environment: + +```bash +arcane-cli config set previews.allEnvironments true +arcane-cli containers list +arcane-cli containers start nginx +``` + +Preview includes the visible, enabled environments returned by your server, including local Docker. Text lists use one combined table with an `ENVIRONMENT` column containing each environment's name, followed by a combined total. Structured details retain environment headings. Resources with identical names or IDs in different environments remain separate. List filters, sorting, limits, and `--start` apply separately to each environment. `--all` requests every matching item per environment and keeps its existing flag restrictions. + +An explicit `--env ` overrides preview for one command. Your saved default environment is preserved; disabling preview restores it: + +```bash +arcane-cli --env 0 containers list +arcane-cli config set previews.allEnvironments false +``` + +Authentication, environments, registries, repositories, templates, variables, and system backups retain their existing global scope. + +### Choose a resource or destination + +Resource actions search every enabled environment. A unique confirmed match is selected automatically. Multiple matches open a Bubble Tea picker showing resource and environment details. If any search fails, even a single confirmed match requires explicit picker selection. Dependent resources, uploads, downloads, and restores stay in the selected environment. + +Creation, imports, builds, image pulls and uploads, and conversion require a destination picker. JSON and noninteractive commands require `--env` whenever selection is necessary. `--yes` and `--force` never choose a resource or destination. Cancelling a picker sends no mutation. + +### Confirm a fleet operation + +Environment-wide mutations run sequentially across enabled environments after one confirmation showing the operation and environment names. This covers prune, update checks, updater runs, bulk container start/stop, settings and schedule updates, and activity-history clearing. `--yes` and applicable existing confirmation-skip flags bypass confirmation. + +Individual failures do not stop later environments, but the command exits nonzero if any operation fails. Cancellation prevents remaining operations from starting. Preview system upgrades use the existing fleet upgrade endpoint once; explicit `--all` retains its existing behavior. + +### Read aggregate JSON + +Preview reads and fleet operations emit one JSON document. Each `result` retains that command's existing JSON payload, including pagination and extra response fields: + +```json +{ + "success": true, + "environments": [ + { + "environmentId": "0", + "environmentName": "Local Docker", + "result": { + "success": true, + "data": [], + "pagination": { "totalItems": 0 } + } + } + ] +} +``` + +Failed entries contain `error` instead of `result`; aggregate `success` is `false` and the exit status is nonzero. Discovery failure stops the command. An empty enabled-environment list produces an empty successful read. Single-resource actions retain their existing JSON payload and announce the selected environment on stderr. + +## Verify self-update signatures + + + +> [!IMPORTANT] +> Signature verification is a preview feature. Its behavior and output are subject to change at any time. + +Every Arcane release signs its checksum file with the Arcane [cosign key](https://github.com/getarcaneapp/arcane/blob/main/cosign.pub) and records the signature in Sigstore's public transparency log. With this preview on, `arcane-cli self-update` checks that signature before it trusts any checksum: + +```bash +arcane-cli config set previews.newSelfUpdater true +arcane-cli self-update run +``` + +The CLI downloads the checksum file and its `.sigstore.json` bundle, then confirms the checksum file was signed with the Arcane key, is recorded in the transparency log, and has not changed. Only then does it check the downloaded binary against that checksum. The cosign key is built into the CLI, so you don't need `cosign` installed. + +If verification fails, the update stops and your binary is left unchanged. The CLI does not fall back to an unverified update. Verification also runs with `--dry-run` and `--json`, and the JSON output reports `signatureVerified` and `bundleUrl`. + +### Network access and caching + +The first verified update downloads Sigstore's trust data from `tuf-repo-cdn.sigstore.dev`. The CLI caches it in `arcane-cli/sigstore` under your user cache directory, which is `~/.cache` on Linux and `~/Library/Caches` on macOS. Later updates use the cache, including offline, until the trust data expires. After that the CLI needs to reach `tuf-repo-cdn.sigstore.dev` again. + +### Older releases + +Releases before v1.18.0 are not signed, so you can't install them with this preview on. To install one, turn the preview off first: + +```bash +arcane-cli config set previews.newSelfUpdater false +arcane-cli self-update --version v1.17.4 +``` + +A signature proves Arcane published a release. It does not stop you from installing an older signed release, for example with `--version`. + +## Reference + +### Config file + +The config file is at `~/.config/arcanecli.yml` by default. Print the exact path on your system with: + +```bash +arcane-cli config path +``` + +A typical config file: + +```yaml +previews: + allEnvironments: false + newSelfUpdater: false +api_key: '' +cli_update_channel: stable +default_environment: '0' +federated_audience: '' +log_level: info +pagination: + default: + limit: 20 + resources: + containers: + limit: 50 + images: + limit: 100 +server_url: http://localhost:3552 +``` + +### Auth file + +`auth login`, `auth refresh`, `auth federated --persist`, and `config set jwt-token` save session tokens to `~/.arcanecli/auth.json` with owner-only permissions. With `--json`, `auth login` and `auth refresh` print the tokens instead of saving them. Tokens are stored per server URL, so a session for one server is never sent to another. `auth logout` removes the current server's session. + +```json +{ + "https://arcane.example.com": { + "accessToken": "eyJ...", + "refreshToken": "..." + } +} +``` + +> [!WARNING] +> Older versions saved `jwt_token` and `refresh_token` in the config file. These keys are deprecated and stop working in v3. The CLI still reads them and prints a warning. Run `arcane-cli auth refresh` to move the session to `auth.json`. + +If `auth.json` is damaged, the CLI ignores it with a warning but can't save new sessions. Run `arcane-cli config backup --auth` to move it to `auth.json.bak`, then sign in again. + +API keys set with `arcane-cli config set api-key` stay in the config file. A config with an API key ignores saved sessions and always authenticates with the key. + +### Global flags + +These flags work on every command. + +| Flag | Purpose | +| ------------------------------ | ------------------------------------------------------------------------ | +| `--output ` | Output mode, `text` or `json`. `--json` is an alias for `--output json`. | +| `--env ` | Select one environment, overriding preview and the configured default. | +| `--yes`, `-y` | Auto-confirm destructive prompts. | +| `--no-color` | Disable ANSI color output. | +| `--request-timeout ` | Override the HTTP timeout for one command. | +| `--config`, `-c ` | Use a config file other than the default. | +| `--log-level ` | Set verbosity: `debug`, `info`, `warn`, `error`, or `fatal`. | +| `--log-json` | Emit structured JSON logs. | diff --git a/src/content/docs/docs/reference/environment-variables.mdx b/src/content/docs/docs/reference/environment-variables.mdx index db6e209d..76368062 100644 --- a/src/content/docs/docs/reference/environment-variables.mdx +++ b/src/content/docs/docs/reference/environment-variables.mdx @@ -44,3 +44,7 @@ If `TZ` is unset, Arcane uses the container's local time, which is UTC on the of ## Admin API key bootstrap Set `ADMIN_STATIC_API_KEY` when automation needs a known API key from the first start. At startup, Arcane creates or updates a protected admin API key with this value, so you don't have to create it in the UI. See the [API Reference](/docs/reference/api) for usage and webhook examples. + +## Observability + +Arcane exports metrics, traces, and logs when the standard `OTEL_*` exporter variables are set. See [OpenTelemetry](/docs/settings/opentelemetry) for setup. diff --git a/src/content/docs/docs/security/socket-proxy.md b/src/content/docs/docs/security/socket-proxy.md index 8c91ec1f..1d08f2c6 100644 --- a/src/content/docs/docs/security/socket-proxy.md +++ b/src/content/docs/docs/security/socket-proxy.md @@ -33,7 +33,7 @@ services: user: '0:0' command: - '-listenip=0.0.0.0' - - '-allowfrom=arcane' + - '-allowfrom=arcane,arcane-upgrader' - '-allowhealthcheck' - '-allowGET=(/v[\d.]+)?/_ping' - '-allowGET=(/v[\d.]+)?/events(/.*)?' @@ -138,7 +138,12 @@ wollomatic blocks every request unless its HTTP method and path are allowed. Thi | `PUT` | container archives | | `DELETE` | containers, images, networks, volumes, nodes, services, secrets, configs | -`-allowfrom=arcane` accepts connections only from the Arcane container, and `-allowhealthcheck` is needed for the proxy's healthcheck. +`-allowfrom=arcane,arcane-upgrader` accepts connections from Arcane and its self-upgrade helper. `arcane-upgrader` is a temporary alias on the helper's user-defined Docker network, independent of Arcane's container name. It keeps the helper authorized while Arcane is replaced. `-allowhealthcheck` is needed for the proxy's healthcheck. + +If you rename the Arcane container, replace `arcane` in the allowlist with its name and keep `arcane-upgrader`. The proxy and helper must share a user-defined network, as in the example above. + +> [!IMPORTANT] +> Existing installations using `-allowfrom=arcane` must add `arcane-upgrader` and recreate the proxy. Install the Arcane release containing this fix once through Docker Compose by pulling and recreating the Arcane service. Older Arcane versions create helpers without the alias, even when they pull a newer helper image. Subsequent self-upgrades can use the updated allowlist; no subnet-wide access is needed. ### Tecnativa docker-socket-proxy diff --git a/src/content/docs/docs/security/vulnerability-scans.mdx b/src/content/docs/docs/security/vulnerability-scans.mdx index 974a455d..5abfb820 100644 --- a/src/content/docs/docs/security/vulnerability-scans.mdx +++ b/src/content/docs/docs/security/vulnerability-scans.mdx @@ -46,6 +46,8 @@ The overview contains: Use **Fixable** in the Vulnerabilities table to show only findings with a known fixed version. This filters saved results and doesn't change what future scans collect. To stop scans from recording unfixable findings at all, turn on **Only Report Fixable Vulnerabilities** (see [Configure scans](#configure-scans)). +Choosing **All** under **Rows per page** asks for confirmation, because loading every finding can slow the browser. The table goes back to 20 rows the next time you open it. + Click **Export CSV** to download every result that matches the current search and filters, including **Show ignored** and **Fixable**, across all pages. ## Patch image vulnerabilities diff --git a/src/content/docs/docs/settings/analytics.md b/src/content/docs/docs/settings/analytics.md index b0404679..45868769 100644 --- a/src/content/docs/docs/settings/analytics.md +++ b/src/content/docs/docs/settings/analytics.md @@ -28,10 +28,10 @@ Arcane doesn't send user identifiers, project metadata, secrets, tokens, or envi A successful heartbeat log looks like this: ``` -Jan 31 21:10:26.504 INF analytics heartbeat sent successfully jobName=analytics-heartbeat version=unknown instanceID=5bd274b3-7500-74b3-aa06-59308f0a0eb2 serverType=manager heartbeatURL=http://localhost:8080/heartbeat env=development +Jan 31 21:10:26.504 INF analytics heartbeat sent successfully version=unknown instanceId=5bd274b3-7500-74b3-aa06-59308f0a0eb2 serverType=manager ``` -Only `version`, `instanceID`, and `serverType` are sent. The other fields (`jobName`, `heartbeatURL`, `env`) are local context. +If a heartbeat fails, Arcane tries again about an hour later. > [!NOTE] > If you want to send analytics but the check-in is blocked: diff --git a/src/content/docs/docs/settings/appearance.md b/src/content/docs/docs/settings/appearance.md index 0fec675e..941a9766 100644 --- a/src/content/docs/docs/settings/appearance.md +++ b/src/content/docs/docs/settings/appearance.md @@ -58,5 +58,5 @@ Upload a custom profile picture from **Account**. Arcane accepts PNG, JPEG, and These settings apply to every user and are under **Settings → Users**: -- **Enable Gravatar** — use Gravatar as the fallback source for users without an uploaded photo. +- **Enable Gravatar** — use Gravatar as the fallback source for users without an uploaded photo. Off by default on new installations; upgraded installations keep their current value. Setting `ENABLE_GRAVATAR=true` or `false` on the Arcane container overrides this setting and locks it in the UI. - **Profile Picture Upload Size (MB)** — maximum cropped image size users can upload. The default is 2 MB, and the allowed range is 1–50 MB. diff --git a/src/content/docs/docs/settings/opentelemetry.md b/src/content/docs/docs/settings/opentelemetry.md new file mode 100644 index 00000000..e3a42e8c --- /dev/null +++ b/src/content/docs/docs/settings/opentelemetry.md @@ -0,0 +1,148 @@ +--- +title: 'OpenTelemetry' +description: 'Send Arcane metrics, traces, and logs to an OpenTelemetry collector.' +--- + +Arcane can export metrics, traces, and logs with OpenTelemetry. It is configured with the standard `OTEL_*` environment variables, and every exporter is off until you turn it on. + +You need: + +- An OpenTelemetry Collector, or any backend that accepts OTLP. +- Somewhere to store the data. The examples below use Prometheus for metrics, Tempo for traces, and Loki for logs. + +## Enable export + +Set these variables on the Arcane container: + +```yaml +environment: + - OTEL_METRICS_EXPORTER=otlp + - OTEL_TRACES_EXPORTER=otlp + - OTEL_LOGS_EXPORTER=otlp + - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 +``` + +Leave out any signal you don't want. Setting only the endpoint doesn't send anything. + +Arcane sends OTLP over HTTP/protobuf to port `4318`. To use gRPC instead, set `OTEL_EXPORTER_OTLP_PROTOCOL=grpc` and point the endpoint at port `4317`. If your collector needs authentication, set `OTEL_EXPORTER_OTLP_HEADERS`, for example `authorization=Bearer `. + +Set the same variables on agents to collect their data too. Each installation reports its own instance ID, and the `arcane.mode` attribute (`manager`, `agent`, or `edge`) tells them apart. + +## Run a collector + +This Compose file runs Arcane next to an OpenTelemetry Collector: + +```yaml +services: + arcane: + image: ghcr.io/getarcaneapp/manager:latest + environment: + - OTEL_METRICS_EXPORTER=otlp + - OTEL_TRACES_EXPORTER=otlp + - OTEL_LOGS_EXPORTER=otlp + - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 + # ...the rest of your Arcane service + + otel-collector: + image: otel/opentelemetry-collector-contrib:latest + command: ['--config=/etc/otelcol/config.yaml'] + volumes: + - ./collector.yaml:/etc/otelcol/config.yaml:ro +``` + +`collector.yaml` receives OTLP and forwards each signal to its backend: + +```yaml +receivers: + otlp: + protocols: + http: + endpoint: 0.0.0.0:4318 + grpc: + endpoint: 0.0.0.0:4317 + +processors: + memory_limiter: + check_interval: 1s + limit_mib: 256 + batch: {} + +exporters: + otlphttp/prometheus: + endpoint: http://prometheus:9090/api/v1/otlp + otlp/tempo: + endpoint: tempo:4317 + tls: + insecure: true + otlphttp/loki: + endpoint: http://loki:3100/otlp + +service: + pipelines: + metrics: + receivers: [otlp] + processors: [memory_limiter, batch] + exporters: [otlphttp/prometheus] + traces: + receivers: [otlp] + processors: [memory_limiter, batch] + exporters: [otlp/tempo] + logs: + receivers: [otlp] + processors: [memory_limiter, batch] + exporters: [otlphttp/loki] +``` + +Prometheus must be started with `--web.enable-otlp-receiver` to accept OTLP metrics. + +## Scrape with Prometheus instead + +If you only want metrics and prefer scraping, skip the collector: + +```yaml +environment: + - OTEL_METRICS_EXPORTER=prometheus + - OTEL_EXPORTER_PROMETHEUS_HOST=0.0.0.0 +``` + +Arcane then serves metrics at `http://:9464/metrics`. Change the port with `OTEL_EXPORTER_PROMETHEUS_PORT`. + +Add a scrape job named `arcane` so the dashboard finds the metrics: + +```yaml +scrape_configs: + - job_name: arcane + static_configs: + - targets: ['arcane:9464'] +``` + +Web UI metrics are only sent over OTLP, so the browser panels stay empty when you scrape. + +## Import the dashboard + +In Grafana, go to **Dashboards → New → Import**, enter dashboard ID `25894`, and pick your Prometheus, Tempo, and Loki data sources. The dashboard is also on [grafana.com](https://grafana.com/grafana/dashboards/25894). It expects metric names with Prometheus suffixes, such as `http_server_request_duration_seconds`, which is what Prometheus's OTLP receiver produces by default. + +## What Arcane sends + +- **Metrics:** API request rates and latency, containers, images, volumes, networks, and projects, per-container CPU, memory, network, and disk usage, image updates, vulnerability counts, job runs, edge agents, GitOps syncs, backups, notifications, Go runtime, and database connections. +- **Traces:** API requests, Docker and Compose calls, database queries, agent calls, jobs, GitOps syncs, backups, image patches, vulnerability scans, and registry calls. +- **Logs:** everything Arcane logs at the configured `LOG_LEVEL`. Logs still go to stdout too. + +Database spans contain SQL statements without their values. Authenticated API request spans include the user's ID and username. URLs are recorded without query strings, and request bodies and credentials are never recorded. + +The manager's web UI also reports to your collector as `arcane-frontend`: page loads and API calls as traces, navigation times and Web Vitals as metrics, and JavaScript errors as logs. Each of these is sent only when that signal uses OTLP over HTTP, and it goes through Arcane at `/api/telemetry/*`, so your collector doesn't need to be reachable from the browser. Behind a reverse proxy, set [`TRUSTED_PROXIES`](/docs/networking/reverse-proxy#trust-the-proxy-with-trusted_proxies) so Arcane rate-limits this per browser instead of per proxy. + +## Other settings + +These standard variables also work: + +| Variable | Use | +| ------------------------------------------------ | ------------------------------------------------------------- | +| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` (and `_TRACES_`, `_LOGS_`) | Send one signal to a different endpoint. | +| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | Keep only some traces, for example `parentbased_traceidratio` with `0.25`. | +| `OTEL_RESOURCE_ATTRIBUTES` | Add attributes such as `deployment.environment=prod`. | +| `OTEL_SDK_DISABLED` | Set to `true` to turn off all telemetry. | + +## Profiling + +Administrators can download Go profiles from Arcane at `/api/debug/pprof/`, for example `/api/debug/pprof/profile?seconds=30` or `/api/debug/pprof/heap`. Open them with `go tool pprof`. diff --git a/src/lib/components/binary-downloads.svelte b/src/lib/components/binary-downloads.svelte index c40474cd..5e02a9af 100644 --- a/src/lib/components/binary-downloads.svelte +++ b/src/lib/components/binary-downloads.svelte @@ -1,4 +1,5 @@