Skip to content

Modern Docker Management, Designed for Everyone

docs: update remote environment documentation

Kyle Mendell9e21050043bb
diff --git a/docs/docs/features/agents/_category_.json b/docs/docs/features/agents/_category_.json
deleted file mode 100644
index 77dbe7f85..000000000
--- a/docs/docs/features/agents/_category_.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "label": "Agents",
- "collapsible": true,
- "collapsed": true
-}
diff --git a/docs/docs/features/agents/setup-agent.md b/docs/docs/features/agents/setup-agent.md
deleted file mode 100644
index 4420d8d39..000000000
--- a/docs/docs/features/agents/setup-agent.md
+++ /dev/null
@@ -1,157 +0,0 @@
-# Agent Setup Guide
-
-> **⚠️ Preview Feature**
-> Agents are currently in preview and subject to significant changes. APIs, configuration formats, and functionality may change between versions without notice. Use with caution in production environments, because of this documentation may not cover all options.
-
-## Overview
-
-Arcane agents are lightweight Go applications that run on remote servers to manage Docker containers and stacks. They communicate with your main Arcane instance via HTTP API.
-
-## Architecture
-
-```
-┌─────────────────┐ HTTP API ┌─────────────────┐
-│ Arcane Server │ ◄────────────── │ Go Agent │
-│ (Management) │ │ (Remote Host) │
-└─────────────────┘ └─────────────────┘
-```
-
-## Prerequisites
-
-- Docker Engine 20.10+
-- Network access to Arcane server
-- User with Docker socket permissions
-
-## Configuration
-
-The agent supports the following environment variables:
-
-| Environment Variable | Default Value | Description |
-| -------------------- | ----------------------------- | ----------------------------------------- |
-| `ARCANE_HOST` | `localhost` | Hostname of the Arcane server |
-| `ARCANE_PORT` | `3000` | Port of the Arcane server |
-| `TLS_ENABLED` | `false` | Enable TLS/HTTPS for server communication |
-| `RECONNECT_DELAY` | `5s` | Delay between reconnection attempts |
-| `HEARTBEAT_RATE` | `30s` | Interval for sending heartbeat to server |
-| `COMPOSE_BASE_PATH` | `data/agent/compose-projects` | Base directory for compose projects |
-
-### Configuration File
-
-Create a `.env` file for the agent:
-
-```bash
-# .env file example
-ARCANE_HOST=your-server.com
-ARCANE_PORT=3000
-TLS_ENABLED=false
-RECONNECT_DELAY=5s
-HEARTBEAT_RATE=30s
-COMPOSE_BASE_PATH=/opt/agent/compose-projects
-```
-
-## Quick Start with Docker
-
-```bash
-# Run the agent with Docker
-docker run -d --name arcane-agent \
- -e ARCANE_HOST=your-server.com \
- -e ARCANE_PORT=3000 \
- -e TLS_ENABLED=false \
- -e HEARTBEAT_RATE=30s \
- -e COMPOSE_BASE_PATH=/data/compose-projects \
- -v /var/run/docker.sock:/var/run/docker.sock \
- -v $(pwd)/compose-projects:/data/compose-projects \
- ghcr.io/ofkm/arcane-agent:latest
-```
-
-## Installation Options
-
-### Docker Compose
-
-```yaml
-services:
- arcane-agent:
- image: ghcr.io/ofkm/arcane-agent:latest
- container_name: arcane-agent
- restart: unless-stopped
- environment:
- - ARCANE_HOST=your-server.com
- - ARCANE_PORT=3000
- - TLS_ENABLED=false
- - HEARTBEAT_RATE=30s
- - RECONNECT_DELAY=5s
- - COMPOSE_BASE_PATH=/data/compose-projects
- volumes:
- - /var/run/docker.sock:/var/run/docker.sock
- - ./compose-projects:/data/compose-projects
-```
-
-### Binary Installation
-
-```bash
-# Download the binary
-wget https://github.com/ofkm/arcane-agent/releases/latest/download/arcane-agent-linux-amd64
-
-# Make executable
-chmod +x arcane-agent-linux-amd64
-
-# Create configuration
-cat > .env << EOF
-ARCANE_HOST=your-server.com
-ARCANE_PORT=3000
-TLS_ENABLED=false
-HEARTBEAT_RATE=30s
-COMPOSE_BASE_PATH=/opt/agent/compose-projects
-EOF
-
-# Run the agent
-./arcane-agent-linux-amd64
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**Agent not registering**: Check network connectivity to Arcane server
-
-```bash
-curl -I http://your-arcane-server:3000/api/agents/register
-```
-
-**Docker permission denied**: Ensure agent user is in docker group
-
-```bash
-sudo usermod -aG docker arcane-agent
-sudo systemctl restart arcane-agent
-```
-
-**TLS Certificate Issues**: When using `TLS_ENABLED=true`, ensure valid certificates
-
-```bash
-# Test TLS connection
-curl -I https://your-arcane-server:3000/api/agents/register
-```
-
-## Updates
-
-### Docker Updates
-
-```bash
-# Pull new image
-docker pull ghcr.io/ofkm/arcane-agent:latest
-
-# Stop and remove old container
-docker stop arcane-agent
-docker rm arcane-agent
-
-# Start with new image (using same configuration)
-docker run -d --name arcane-agent \
- --env-file .env \
- -v /var/run/docker.sock:/var/run/docker.sock \
- -v $(pwd)/compose-projects:/data/compose-projects \
- ghcr.io/ofkm/arcane-agent:latest
-```
-
----
-
-> **Note**: This feature is under active development. For support or to report issues, please visit our [GitHub repository](https://github.com/ofkm/arcane-agent).
diff --git a/docs/docs/features/environments/_category_.json b/docs/docs/features/environments/_category_.json
new file mode 100644
index 000000000..b724361b6
--- /dev/null
+++ b/docs/docs/features/environments/_category_.json
@@ -0,0 +1,5 @@
+{
+ "label": "Environments",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/docs/docs/features/environments/setup-agent.md b/docs/docs/features/environments/setup-agent.md
new file mode 100644
index 000000000..6ce066064
--- /dev/null
+++ b/docs/docs/features/environments/setup-agent.md
@@ -0,0 +1,96 @@
+# Environments Setup Guide
+
+## Overview
+
+Remote Environments use the Arcane agent to expose the Docker API of a remote host. This allows for management of docker resources from a centralized server.
+
+## Architecture
+
+```
+┌─────────────────┐ HTTP API ┌─────────────────┐
+│ Arcane Server │ ──────────────> │ Go Agent │
+│ (Management) │ <────────────── │ (Remote Host) │
+└─────────────────┘ HTTP RESPONSE └─────────────────┘
+```
+
+## Prerequisites
+
+- Docker Engine 20.10+
+- Network access to Arcane server
+- User with Docker socket permissions
+
+## Configuration
+
+The agent supports the following environment variables:
+
+| Environment Variable | Default Value | Description |
+| -------------------- | ----------------------------- | ------------------------------------------------ |
+| `AGENT_ID` | `<hostname-of-your-server` | Hostname of the Arcane server |
+| `AGENT_LISTEN_ADDRESS`| `0.0.0.0` | The address to bind to on the agent host |
+| `AGENT_PORT` | `3552` | The Port for the agent to listen on |
+| `API_KEY` | `-` | The API Key generated by the Arcane Server |
+
+
+### Configuration File
+
+Create a `.env` file for the agent:
+
+```bash
+# .env file example
+AGENT_ID=arcane-agent-example
+AGENT_LISTEN_ADDRESS=0.0.0.0
+AGENT_PORT=3552
+API_KEY=your-secret-api-key-here
+```
+
+## Installation Options
+
+### Docker Compose
+
+```yaml
+name: arcane-agent
+services:
+ arcane-agent:
+ container_name: arcane-agent
+ restart: unless-stopped
+ environment:
+ - AGENT_ID=arcane-agent-example
+ - AGENT_LISTEN_ADDRESS=0.0.0.0
+ - AGENT_PORT=3552
+ - API_KEY=your-secret-api-key-here
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ - $(pwd)/compose-projects:/data/compose-projects
+ image: ghcr.io/ofkm/arcane-agent:latest
+```
+
+### Binary Installation
+
+```bash
+# Download the binary
+wget https://github.com/ofkm/arcane-agent/releases/latest/download/arcane-agent-linux-amd64
+
+# Make executable
+chmod +x arcane-agent-linux-amd64
+
+# Create configuration
+cat > .env << EOF
+AGENT_ID=arcane-agent-example
+AGENT_LISTEN_ADDRESS=0.0.0.0
+AGENT_PORT=3552
+API_KEY=your-secret-api-key-here
+EOF
+
+# Run the agent
+./arcane-agent-linux-amd64
+```
+
+## Updates
+
+### Docker Updates
+
+```bash
+docker compose down
+docker compose pull
+docker compose up -d
+```
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 3102e8905..8953c66fd 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -5,75 +5,82 @@ import type * as Preset from '@docusaurus/preset-classic';
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
const config: Config = {
- title: 'Arcane - Documentation',
- tagline: 'Modern Docker management, designed for everyone',
- favicon: 'img/arcane.png',
+ title: 'Arcane - Documentation',
+ tagline: 'Modern Docker management, designed for everyone',
+ favicon: 'img/arcane.png',
- // Set the production url of your site here
- url: 'https://arcane.ofkm.dev',
- // Set the /<baseUrl>/ pathname under which your site is served
- // For GitHub pages deployment, it is often '/<projectName>/'
- baseUrl: '/',
- organizationName: 'ofkm',
- projectName: 'arcane',
- onBrokenLinks: 'warn',
- onBrokenMarkdownLinks: 'warn',
- i18n: {
- defaultLocale: 'en',
- locales: ['en']
- },
+ url: 'https://arcane.ofkm.dev',
+ baseUrl: '/',
+ organizationName: 'ofkm',
+ projectName: 'arcane',
+ onBrokenLinks: 'warn',
+ onBrokenMarkdownLinks: 'warn',
+ i18n: {
+ defaultLocale: 'en',
+ locales: ['en'],
+ },
+ future: {
+ v4: {
+ removeLegacyPostBuildHeadAttribute: true,
+ },
+ experimental_faster: true,
+ experimental_faster: {
+ rspackBundler: true,
+ rspackPersistentCache: true,
+ },
+ },
- presets: [
- [
- 'classic',
- {
- docs: {
- sidebarPath: './sidebars.ts'
- },
- theme: {
- customCss: ['./src/css/custom.css', './src/css/docs.css']
- }
- } satisfies Preset.Options
- ]
- ],
+ presets: [
+ [
+ 'classic',
+ {
+ docs: {
+ sidebarPath: './sidebars.ts',
+ },
+ // theme: {
+ // customCss: ['./src/css/custom.css', './src/css/docs.css'],
+ // },
+ } satisfies Preset.Options,
+ ],
+ ],
- themeConfig: {
- navbar: {
- title: 'Arcane',
- logo: {
- alt: 'Arcane',
- src: 'img/arcane.png'
- },
- items: [
- {
- href: 'https://github.com/ofkm/arcane',
- label: 'GitHub',
- position: 'right'
- }
- ]
- },
- prism: {
- theme: prismThemes.vsLight,
- darkTheme: prismThemes.vsDark
- }
- } satisfies Preset.ThemeConfig,
+ themeConfig: {
+ navbar: {
+ title: 'Arcane',
+ logo: {
+ alt: 'Arcane',
+ src: 'img/arcane.png',
+ },
+ items: [
+ {
+ href: 'https://github.com/ofkm/arcane',
+ label: 'GitHub',
+ position: 'right',
+ },
+ ],
+ },
+ prism: {
+ theme: prismThemes.vsLight,
+ darkTheme: prismThemes.vsDark,
+ },
+ } satisfies Preset.ThemeConfig,
- plugins: [
- // Only include the analytics plugin if the environment variable exists
- // This ensures analytics won't run during local development
- ...(process.env.UMAMI_WEBSITE_ID
- ? [
- [
- '@dipakparmar/docusaurus-plugin-umami',
- /** @type {import('@dipakparmar/docusaurus-plugin-umami').Options} */
- {
- websiteID: process.env.UMAMI_WEBSITE_ID,
- analyticsDomain: process.env.UMAMI_ANALYTICS_DOMAIN
- }
- ]
- ]
- : [])
- ]
+ plugins: [
+ // Only include the analytics plugin if the environment variable exists
+ // This ensures analytics won't run during local development
+ ...(process.env.UMAMI_WEBSITE_ID
+ ? [
+ [
+ '@dipakparmar/docusaurus-plugin-umami',
+ /** @type {import('@dipakparmar/docusaurus-plugin-umami').Options} */
+ {
+ websiteID: process.env.UMAMI_WEBSITE_ID,
+ analyticsDomain: process.env.UMAMI_ANALYTICS_DOMAIN,
+ },
+ ],
+ ]
+ : []),
+ ],
};
export default config;
diff --git a/docs/package.json b/docs/package.json
index d67762584..425b0ee89 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -1,49 +1,41 @@
{
- "name": "docs",
- "version": "0.0.0",
- "private": true,
- "scripts": {
- "docusaurus": "docusaurus",
- "start": "docusaurus start",
- "build": "docusaurus build",
- "swizzle": "docusaurus swizzle",
- "deploy": "docusaurus deploy",
- "clear": "docusaurus clear",
- "serve": "docusaurus serve",
- "write-translations": "docusaurus write-translations",
- "write-heading-ids": "docusaurus write-heading-ids",
- "typecheck": "tsc"
- },
- "dependencies": {
- "@dipakparmar/docusaurus-plugin-umami": "^2.2.0",
- "@docusaurus/core": "3.7.0",
- "@docusaurus/preset-classic": "3.7.0",
- "@mdx-js/react": "^3.0.0",
- "clsx": "^2.0.0",
- "prism-react-renderer": "^2.3.0",
- "react": "^19.0.0",
- "react-dom": "^19.0.0",
- "react-feather": "^2.0.10"
- },
- "devDependencies": {
- "@docusaurus/module-type-aliases": "3.7.0",
- "@docusaurus/tsconfig": "3.7.0",
- "@docusaurus/types": "3.7.0",
- "typescript": "~5.6.2"
- },
- "browserslist": {
- "production": [
- ">0.5%",
- "not dead",
- "not op_mini all"
- ],
- "development": [
- "last 3 chrome version",
- "last 3 firefox version",
- "last 5 safari version"
- ]
- },
- "engines": {
- "node": ">=18.0"
- }
+ "name": "docs",
+ "version": "0.0.0",
+ "private": true,
+ "scripts": {
+ "docusaurus": "docusaurus",
+ "start": "docusaurus start",
+ "build": "docusaurus build",
+ "swizzle": "docusaurus swizzle",
+ "deploy": "docusaurus deploy",
+ "clear": "docusaurus clear",
+ "serve": "docusaurus serve",
+ "write-translations": "docusaurus write-translations",
+ "write-heading-ids": "docusaurus write-heading-ids",
+ "typecheck": "tsc"
+ },
+ "dependencies": {
+ "@dipakparmar/docusaurus-plugin-umami": "^2.2.0",
+ "@docusaurus/core": "3.8.0",
+ "@docusaurus/preset-classic": "3.8.0",
+ "@mdx-js/react": "^3.0.0",
+ "clsx": "^2.0.0",
+ "prism-react-renderer": "^2.3.0",
+ "react": "^19.0.0",
+ "react-dom": "^19.0.0",
+ "react-feather": "^2.0.10"
+ },
+ "devDependencies": {
+ "@docusaurus/module-type-aliases": "3.8.0",
+ "@docusaurus/tsconfig": "3.8.0",
+ "@docusaurus/types": "3.8.0",
+ "typescript": "~5.6.2"
+ },
+ "browserslist": {
+ "production": [">0.5%", "not dead", "not op_mini all"],
+ "development": ["last 3 chrome version", "last 3 firefox version", "last 5 safari version"]
+ },
+ "engines": {
+ "node": ">=18.0"
+ }
}