### Quick Dockge Installation Commands

Source: https://context7.com/louislam/dockge/llms.txt

These commands quickly set up Dockge by downloading the compose file and starting the service. Ensure the specified paths for stacks and Dockge data exist.

```bash
# Quick installation commands
mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge

# Download compose.yaml with custom settings
curl "https://dockge.kuma.pet/compose.yaml?port=5001&stacksPath=/opt/stacks" --output compose.yaml

# Start Dockge
docker compose up -d

# Dockge is now running on http://localhost:5001

```

--------------------------------

### Install Dockge with Docker Compose

Source: https://github.com/louislam/dockge/blob/master/README.md

Basic installation steps for Dockge using Docker. This involves creating directories, downloading the compose.yaml file, and starting the service.

```bash
mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml
docker compose up -d
```

```bash
# If you are using docker-compose V1 or Podman
# docker-compose up -d
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/louislam/dockge/blob/master/CONTRIBUTING.md

Installs all necessary Node.js packages for development. Ensure Node.js and npm are installed before running.

```bash
npm install
```

--------------------------------

### Stack Management - Start Stack

Source: https://context7.com/louislam/dockge/llms.txt

Starts a stopped Docker Compose stack.

```APIDOC
## Start Stack

### Description
Starts a stopped Docker Compose stack.

### Method
SOCKET.EMIT

### Endpoint
`agent` with action `startStack`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agent** (string) - Should be empty string `""`.
- **action** (string) - Must be `"startStack"`.
- **stackName** (string) - Required - The name of the stack to start.

### Request Example
```javascript
socket.emit("agent", "", "startStack", "my-nginx", (response) => {
  if (response.ok) {
    console.log("Stack started:", response.msg);
  } else {
    console.error("Failed to start stack:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the stack was started successfully.
- **msg** (string) - Confirmation message, e.g., "Started".
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Failure Response
- **ok** (boolean) - Indicates if starting the stack failed.
- **msg** (string) - Error message.

#### Response Example
```json
{
  "ok": true,
  "msg": "Started",
  "msgi18n": true
}
```
```

--------------------------------

### Service Management - Start Service

Source: https://context7.com/louislam/dockge/llms.txt

Starts a specific service within a given stack. Requires the stack name and the service name.

```APIDOC
## POST /agent

### Description
Starts a specific service within a stack.

### Method
SOCKET

### Endpoint
/agent

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute, 'startService'.
- **stackName** (string) - Required - The name of the stack containing the service.
- **serviceName** (string) - Required - The name of the service to start.

### Request Example
```json
{
  "command": "startService",
  "stackName": "my-stack",
  "serviceName": "nginx"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **msg** (string) - A message describing the result.

#### Response Example
```json
{
  "ok": true,
  "msg": "Service nginx started"
}
```
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/louislam/dockge/blob/master/CONTRIBUTING.md

Starts the frontend development server, which binds to 0.0.0.0:5000. This server is for development purposes only and will be compiled to the frontend-dist directory for production.

```bash
npm run dev:frontend
```

--------------------------------

### Start Individual Service

Source: https://context7.com/louislam/dockge/llms.txt

Initiates the startup of a specific service within a given stack. Requires the stack name and the service name.

```javascript
// Start a specific service within a stack
socket.emit("agent", "", "startService", "my-stack", "nginx", (response) => {
  if (response.ok) {
    console.log("Service started:", response.msg);
  } else {
    console.error("Failed to start service:", response.msg);
  }
});

// Success response: { ok: true, msg: "Service nginx started" }
```

--------------------------------

### Authentication - Setup Initial User

Source: https://context7.com/louislam/dockge/llms.txt

This endpoint is used to create the initial administrator user for Dockge. It is a public endpoint and does not require authentication.

```APIDOC
## POST /socket.io/setup

### Description
Creates the initial administrator user for Dockge. This is a public endpoint.

### Method
SOCKET.IO EMIT

### Endpoint
`setup`

### Parameters
#### Request Body
- **username** (string) - Required - The desired username for the admin user.
- **password** (string) - Required - The desired password for the admin user.

### Request Example
```javascript
// Socket.IO client setup
import { io } from "socket.io-client";
const socket = io("http://localhost:5001");

// Initial setup - Create first admin user (public endpoint)
socket.emit("setup", "admin", "SecurePassword123!", (response) => {
  if (response.ok) {
    console.log("User created successfully:", response.msg);
  } else {
    console.error("Setup failed:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **msg** (string) - A message indicating the result of the operation (e.g., "successAdded").
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Response Example
```json
{
  "ok": true,
  "msg": "successAdded",
  "msgi18n": true
}
```
```

--------------------------------

### Run Backend Development Server

Source: https://github.com/louislam/dockge/blob/master/CONTRIBUTING.md

Starts the backend development server, which binds to 0.0.0.0:5001. This server is primarily a socket.io and express.js application.

```bash
npm run dev:backend
```

--------------------------------

### Start a Stopped Stack

Source: https://context7.com/louislam/dockge/llms.txt

Initiate the startup process for a Docker stack that is currently stopped. This command requires the stack name.

```javascript
// Start a stopped stack
socket.emit("agent", "", "startStack", "my-nginx", (response) => {
  if (response.ok) {
    console.log("Stack started:", response.msg);
  } else {
    console.error("Failed to start stack:", response.msg);
  }
});

// Success response: { ok: true, msg: "Started", msgi18n: true }
```

--------------------------------

### Dockge Socket.IO - Setup Initial User

Source: https://context7.com/louislam/dockge/llms.txt

Use this JavaScript snippet to connect to Dockge's Socket.IO API and set up the initial administrator user. Ensure the client is configured to connect to the correct Dockge instance.

```javascript
// Socket.IO client setup
import { io } from "socket.io-client";
const socket = io("http://localhost:5001");

// Initial setup - Create first admin user (public endpoint)
socket.emit("setup", "admin", "SecurePassword123!", (response) => {
  if (response.ok) {
    console.log("User created successfully:", response.msg);
  } else {
    console.error("Setup failed:", response.msg);
  }
});

// Expected response:
// { ok: true, msg: "successAdded", msgi18n: true }

```

--------------------------------

### Advanced Dockge Installation with Custom Paths

Source: https://github.com/louislam/dockge/blob/master/README.md

Download a custom compose.yaml file for Dockge, allowing specification of the port and the directory for storing stacks. This is useful for non-default configurations.

```bash
# Download your compose.yaml
curl "https://dockge.kuma.pet/compose.yaml?port=5001&stacksPath=/opt/stacks" --output compose.yaml
```

--------------------------------

### Get Application Settings

Source: https://context7.com/louislam/dockge/llms.txt

Retrieve the current application settings. The response contains settings like 'disableAuth', 'primaryHostname', and 'globalENV'.

```javascript
// Get application settings
socket.emit("getSettings", (response) => {
  if (response.ok) {
    console.log("Settings:", response.data);
    // {
    //   disableAuth: false,
    //   primaryHostname: "localhost",
    //   globalENV: "# VARIABLE=value #comment"
    // }
  }
});
```

--------------------------------

### Docker Information - Get Docker Network List

Source: https://context7.com/louislam/dockge/llms.txt

Retrieves a list of all Docker networks available on the system.

```APIDOC
## POST /agent

### Description
Gets a list of Docker networks.

### Method
SOCKET

### Endpoint
/agent

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute, 'getDockerNetworkList'.

### Request Example
```json
{
  "command": "getDockerNetworkList"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **dockerNetworkList** (array) - An array of strings, where each string is a Docker network name.

#### Response Example
```json
{
  "ok": true,
  "dockerNetworkList": [
    "bridge",
    "host",
    "none",
    "my-custom-network"
  ]
}
```
```

--------------------------------

### Basic Dockge Docker Compose Deployment

Source: https://context7.com/louislam/dockge/llms.txt

Use this compose file for a basic Dockge installation. Ensure the volumes for Docker socket, data, and stacks directory are correctly mapped.

```yaml
# compose.yaml - Basic Dockge installation
services:
  dockge:
    image: louislam/dockge:1
    restart: unless-stopped
    ports:
      # Host Port : Container Port
      - 5001:5001
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data

      # If you want to use private registries, share the auth file:
      # - /root/.docker/:/root/.docker

      # Stacks Directory (paths must match on both sides)
      - /opt/stacks:/opt/stacks
    environment:
      # Tell Dockge where your stacks directory is
      - DOCKGE_STACKS_DIR=/opt/stacks
      # Set stack file ownership (both required)
      - PUID=1000
      - PGID=1000

```

--------------------------------

### Stack Management - Get Stack Details

Source: https://context7.com/louislam/dockge/llms.txt

Retrieves detailed information about a specific Docker Compose stack.

```APIDOC
## Get Stack Details

### Description
Retrieves detailed information about a specific Docker Compose stack.

### Method
SOCKET.EMIT

### Endpoint
`agent` with action `getStack`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agent** (string) - Should be empty string `""`.
- **action** (string) - Must be `"getStack"`.
- **stackName** (string) - Required - The name of the stack to retrieve details for.

### Request Example
```javascript
socket.emit("agent", "", "getStack", "my-nginx", (response) => {
  if (response.ok) {
    const stack = response.stack;
    console.log("Stack name:", stack.name);
    console.log("Status:", stack.status);
    console.log("Compose YAML:", stack.composeYAML);
    console.log("Environment:", stack.composeENV);
    console.log("Managed by Dockge:", stack.isManagedByDockge);
  } else {
    console.error("Failed to get stack:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the stack details were retrieved successfully.
- **stack** (object) - An object containing the stack details:
  - **name** (string) - The name of the stack.
  - **status** (number) - The current status of the stack (0=unknown, 1=draft, 2=created, 3=running, 4=exited).
  - **composeYAML** (string) - The content of the `docker-compose.yaml` file.
  - **composeENV** (string) - The content of the `.env` file.
  - **isManagedByDockge** (boolean) - Whether the stack is managed by Dockge.
  - **composeFileName** (string) - The name of the compose file.
  - **primaryHostname** (string) - The primary hostname for the stack.

#### Failure Response
- **ok** (boolean) - Indicates if retrieving stack details failed.
- **msg** (string) - Error message.

#### Response Example
```json
{
  "ok": true,
  "stack": {
    "name": "my-nginx",
    "status": 3,
    "composeYAML": "services:\n  nginx:\n    image: nginx:latest...",
    "composeENV": "NGINX_HOST=localhost",
    "isManagedByDockge": true,
    "composeFileName": "compose.yaml",
    "primaryHostname": "localhost"
  }
}
```
```

--------------------------------

### Update Dockge

Source: https://github.com/louislam/dockge/blob/master/README.md

To update Dockge, navigate to the installation directory and run the docker compose pull and up commands.

```bash
cd /opt/dockge
docker compose pull && docker compose up -d
```

--------------------------------

### Restart a Stack

Source: https://context7.com/louislam/dockge/llms.txt

Restart a Docker stack, which involves stopping and then starting it again. The stack name is required for this operation.

```javascript
// Restart a stack
socket.emit("agent", "", "restartStack", "my-nginx", (response) => {
  if (response.ok) {
    console.log("Stack restarted:", response.msg);
  } else {
    console.error("Failed to restart stack:", response.msg);
  }
});

// Success response: { ok: true, msg: "Restarted", msgi18n: true }
```

--------------------------------

### Docker Information - Get Docker Stats

Source: https://context7.com/louislam/dockge/llms.txt

Retrieves resource usage statistics for all running Docker containers.

```APIDOC
## POST /agent

### Description
Gets container resource usage statistics.

### Method
SOCKET

### Endpoint
/agent

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute, 'dockerStats'.

### Request Example
```json
{
  "command": "dockerStats"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **dockerStats** (object) - An object where keys are container names and values are objects containing resource usage statistics.

#### Response Example
```json
{
  "ok": true,
  "dockerStats": {
    "my-nginx-1": {
      "Name": "my-nginx-1",
      "CPUPerc": "0.00%",
      "MemUsage": "2.5MiB / 7.77GiB",
      "NetIO": "1.2kB / 0B",
      "BlockIO": "0B / 0B"
    }
  }
}
```
```

--------------------------------

### Get Docker Network List

Source: https://context7.com/louislam/dockge/llms.txt

Retrieves a list of all available Docker networks on the system. This includes default networks and any custom networks that have been created.

```javascript
// Get list of Docker networks
socket.emit("agent", "", "getDockerNetworkList", (response) => {
  if (response.ok) {
    console.log("Networks:", response.dockerNetworkList);
    // ["bridge", "host", "none", "my-custom-network"]
  }
});
```

--------------------------------

### Get Stack Details

Source: https://context7.com/louislam/dockge/llms.txt

Retrieve detailed information about a specific Docker stack by its name. The response includes status, compose configuration, and management details.

```javascript
// Get details of a specific stack
socket.emit("agent", "", "getStack", "my-nginx", (response) => {
  if (response.ok) {
    const stack = response.stack;
    console.log("Stack name:", stack.name);
    console.log("Status:", stack.status);  // 0=unknown, 1=draft, 2=created, 3=running, 4=exited
    console.log("Compose YAML:", stack.composeYAML);
    console.log("Environment:", stack.composeENV);
    console.log("Managed by Dockge:", stack.isManagedByDockge);
  } else {
    console.error("Failed to get stack:", response.msg);
  }
});

// Success response:
// {
//   ok: true,
//   stack: {
//     name: "my-nginx",
//     status: 3,
//     composeYAML: "services:\n  nginx:\n    image: nginx:latest...",
//     composeENV: "NGINX_HOST=localhost",
//     isManagedByDockge: true,
//     composeFileName: "compose.yaml",
//     primaryHostname: "localhost"
//   }
// }
```

--------------------------------

### Service Management - Get Service Status List

Source: https://context7.com/louislam/dockge/llms.txt

Retrieves the status of all services within a specified stack. Requires the stack name.

```APIDOC
## POST /agent

### Description
Gets the status of all services in a stack.

### Method
SOCKET

### Endpoint
/agent

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute, 'serviceStatusList'.
- **stackName** (string) - Required - The name of the stack.

### Request Example
```json
{
  "command": "serviceStatusList",
  "stackName": "my-stack"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **serviceStatusList** (object) - An object where keys are service names and values are arrays of container status objects.

#### Response Example
```json
{
  "ok": true,
  "serviceStatusList": {
    "nginx": [
      {
        "status": "running",
        "name": "my-stack-nginx-1"
      }
    ],
    "redis": [
      {
        "status": "running",
        "name": "my-stack-redis-1"
      }
    ]
  }
}
```
```

--------------------------------

### Get Docker Stats

Source: https://context7.com/louislam/dockge/llms.txt

Fetches resource usage statistics for Docker containers. The response provides metrics such as CPU percentage, memory usage, and network/block I/O.

```javascript
// Get container resource usage statistics
socket.emit("agent", "", "dockerStats", (response) => {
  if (response.ok) {
    console.log("Docker stats:", response.dockerStats);
    // {
    //   "my-nginx-1": {
    //     Name: "my-nginx-1",
    //     CPUPerc: "0.00%",
    //     MemUsage: "2.5MiB / 7.77GiB",
    //     NetIO: "1.2kB / 0B",
    //     BlockIO: "0B / 0B"
    //   }
    // }
  }
});
```

--------------------------------

### Get Service Status List

Source: https://context7.com/louislam/dockge/llms.txt

Retrieves the status of all services within a specified stack. The response includes details like status and container name for each service.

```javascript
// Get status of all services in a stack
socket.emit("agent", "", "serviceStatusList", "my-stack", (response) => {
  if (response.ok) {
    console.log("Service statuses:", response.serviceStatusList);
    // {
    //   "nginx": [{ status: "running", name: "my-stack-nginx-1" }],
    //   "redis": [{ status: "running", name: "my-stack-redis-1" }]
    // }
  }
});
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/louislam/dockge/blob/master/CONTRIBUTING.md

Compiles the frontend application into the 'frontend-dist' directory, preparing it for production deployment. This command is used when the frontend dev server is not needed.

```bash
npm run build
```

--------------------------------

### Dockge Command Line Arguments Configuration

Source: https://context7.com/louislam/dockge/llms.txt

Alternatively, configure Dockge using command-line arguments. This is useful for custom startup scripts or when not using environment variables.

```bash
# Start Dockge with custom settings
tsx ./backend/index.ts \
  --port 5001 \
  --hostname 0.0.0.0 \
  --stacksDir /opt/stacks \
  --dataDir ./data/ \
  --sslKey /path/to/key.pem \
  --sslCert /path/to/cert.pem \
  --sslKeyPassphrase secret \
  --enableConsole

```

--------------------------------

### Deploy New Docker Compose Stack

Source: https://context7.com/louislam/dockge/llms.txt

Deploy a new Docker Compose stack by providing the stack name, compose YAML content, and environment variables. Set `isAdd` to true for new deployments.

```javascript
// Deploy a new Docker Compose stack
const stackName = "my-nginx";
const composeYAML = "\
services:
  nginx:
    image: nginx:latest
    ports:
      - \"8080:80\"
    restart: unless-stopped
";
const composeENV = "\
# Environment variables
NGINX_HOST=localhost
";
const isAdd = true;  // true for new stack, false for update

socket.emit("agent", "", "deployStack", stackName, composeYAML, composeENV, isAdd, (response) => {
  if (response.ok) {
    console.log("Stack deployed successfully:", response.msg);
  } else {
    console.error("Deployment failed:", response.msg);
  }
});

// Success response:
// { ok: true, msg: "Deployed", msgi18n: true }
```

--------------------------------

### Listen for Server Information Events

Source: https://context7.com/louislam/dockge/llms.txt

Use this snippet to listen for various server information events from the Dockge server, such as version, container status, and hostname.

```javascript
// Listen for server information
socket.on("info", (info) => {
  console.log("Server version:", info.version);
  console.log("Latest version:", info.latestVersion);
  console.log("Is container:", info.isContainer);
  console.log("Primary hostname:", info.primaryHostname);
});
```

```javascript
// Listen for setup redirect
socket.on("setup", () => {
  console.log("Redirecting to setup page - no users configured");
});
```

```javascript
// Listen for auto-login (when auth is disabled)
socket.on("autoLogin", () => {
  console.log("Auto-logged in - authentication disabled");
});
```

```javascript
// Listen for refresh request (password changed, forced disconnect)
socket.on("refresh", () => {
  console.log("Server requested page refresh");
  window.location.reload();
});
```

--------------------------------

### Dockge Environment Variables Configuration

Source: https://context7.com/louislam/dockge/llms.txt

Configure Dockge's behavior using these environment variables. Key variables include port, data directory, SSL settings, and file ownership.

```bash
# Server configuration
DOCKGE_PORT=5001                    # Web UI port (default: 5001)
DOCKGE_HOSTNAME=0.0.0.0             # Bind hostname (optional)
DOCKGE_STACKS_DIR=/opt/stacks       # Directory for compose stacks
DOCKGE_DATA_DIR=./data/             # Directory for Dockge data

# SSL/TLS configuration
DOCKGE_SSL_KEY=/path/to/key.pem     # SSL private key path
DOCKGE_SSL_CERT=/path/to/cert.pem   # SSL certificate path
DOCKGE_SSL_KEY_PASSPHRASE=secret    # SSL key passphrase (if encrypted)

# Feature flags
DOCKGE_ENABLE_CONSOLE=true          # Enable web console terminal
DOCKGE_IS_CONTAINER=1               # Set when running in container

# File ownership
PUID=1000                           # User ID for stack files
PGID=1000                           # Group ID for stack files

```

--------------------------------

### Add Remote Dockge Instance as Agent

Source: https://context7.com/louislam/dockge/llms.txt

Add a remote Dockge instance to manage it as an agent. Requires the URL, username, password, and a display name for the agent.

```javascript
// Add a remote Dockge instance as an agent
socket.emit("addAgent", {
  url: "https://remote-dockge.example.com:5001",
  username: "admin",
  password: "RemotePassword123!",
  name: "Production Server"
}, (response) => {
  if (response.ok) {
    console.log("Agent added:", response.msg);
  } else {
    console.error("Failed to add agent:", response.msg);
  }
});

// Success response: { ok: true, msg: "agentAddedSuccessfully", msgi18n: true }
```

--------------------------------

### Authentication - Login with Token

Source: https://context7.com/louislam/dockge/llms.txt

Logs in to the Dockge service using a previously obtained JWT token.

```APIDOC
## Login with Token

### Description
Logs in to the Dockge service using a previously obtained JWT token.

### Method
SOCKET.EMIT

### Endpoint
`loginByToken`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **storedToken** (string) - Required - The JWT token for authentication.

### Request Example
```javascript
const storedToken = localStorage.getItem("token");
socket.emit("loginByToken", storedToken, (response) => {
  if (response.ok) {
    console.log("Token login successful");
  } else {
    console.error("Token invalid or expired:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the login was successful.

#### Failure Response
- **ok** (boolean) - Indicates if the login failed.
- **msg** (string) - Error message, e.g., "authInvalidToken".
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Response Example
```json
{
  "ok": true
}
```

```json
{
  "ok": false,
  "msg": "authInvalidToken",
  "msgi18n": true
}
```
```

--------------------------------

### Request and Listen for Stack List

Source: https://context7.com/louislam/dockge/llms.txt

Request the current list of stacks, which triggers a 'stackList' event with the updated data. Also includes how to listen for these updates.

```javascript
// Request updated stack list (triggers stackList event)
socket.emit("agent", "", "requestStackList", (response) => {
  if (response.ok) {
    console.log("Stack list requested");
  }
});

// Listen for stack list updates
socket.on("agent", (event, data) => {
  if (event === "stackList") {
    console.log("Stack list received:", data.stackList);
    // {
    //   "my-nginx": { name: "my-nginx", status: 3, isManagedByDockge: true, ... },
    //   "postgres": { name: "postgres", status: 3, isManagedByDockge: true, ... }
    // }
  }
});
```

--------------------------------

### Dockge Socket.IO - Login with Credentials

Source: https://context7.com/louislam/dockge/llms.txt

This JavaScript code demonstrates how to log in to Dockge using a username and password via the Socket.IO API. It handles responses for successful login, and when a 2FA token is required.

```javascript
// Login with username and password
socket.emit("login", {
  username: "admin",
  password: "SecurePassword123!",
  token: null  // Optional 2FA token
}, (response) => {
  if (response.ok) {
    console.log("Login successful");
    // Store JWT token for subsequent requests
    localStorage.setItem("token", response.token);
  } else if (response.tokenRequired) {
    console.log("2FA token required");
    // Prompt user for 2FA token and retry
  } else {
    console.error("Login failed:", response.msg);
  }
});

// Success response:
// { ok: true, token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

// 2FA required response:
// { tokenRequired: true }

```

--------------------------------

### Authentication - Login with Credentials

Source: https://context7.com/louislam/dockge/llms.txt

This endpoint is used to log in a user with their credentials. It supports optional two-factor authentication (2FA).

```APIDOC
## POST /socket.io/login

### Description
Logs in a user with their username and password. Supports optional 2FA.

### Method
SOCKET.IO EMIT

### Endpoint
`login`

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.
- **token** (string) - Optional - The 2FA token, if required.

### Request Example
```javascript
// Login with username and password
socket.emit("login", {
  username: "admin",
  password: "SecurePassword123!",
  token: null  // Optional 2FA token
}, (response) => {
  if (response.ok) {
    console.log("Login successful");
    // Store JWT token for subsequent requests
    localStorage.setItem("token", response.token);
  } else if (response.tokenRequired) {
    console.log("2FA token required");
    // Prompt user for 2FA token and retry
  } else {
    console.error("Login failed:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the login was successful.
- **token** (string) - JWT token for authenticated requests.

#### 2FA Required Response
- **tokenRequired** (boolean) - Indicates that a 2FA token is required.

#### Response Example (Success)
```json
{
  "ok": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Response Example (2FA Required)
```json
{
  "tokenRequired": true
}
```
```

--------------------------------

### Default Stacks Directory Structure

Source: https://context7.com/louislam/dockge/llms.txt

Illustrates the default directory structure for managing Docker Compose stacks in Dockge, including compose files and environment variable files.

```bash
# Default stacks directory structure
/opt/stacks/
├── my-nginx/
│   ├── compose.yaml          # Main compose file
│   └── .env                   # Stack-specific environment variables
├── postgres-stack/
│   ├── compose.yaml
│   └── .env
└── global.env                 # Global environment variables (optional)
```

--------------------------------

### Multi-Agent Management

Source: https://context7.com/louislam/dockge/llms.txt

APIs for managing remote Dockge instances as agents.

```APIDOC
## Multi-Agent Management - Add Remote Dockge Instance

### Description
Adds a remote Dockge instance to be managed as an agent.

### Method
`socket.emit`

### Endpoint
`addAgent`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agentInfo** (object) - An object containing the details of the remote agent.
  - **url** (string) - The URL of the remote Dockge instance.
  - **username** (string) - The username for authentication.
  - **password** (string) - The password for authentication.
  - **name** (string) - A display name for the agent.

### Request Example
```javascript
socket.emit("addAgent", {
  url: "https://remote-dockge.example.com:5001",
  username: "admin",
  password: "RemotePassword123!",
  name: "Production Server"
}, (response) => {
  if (response.ok) {
    console.log("Agent added:", response.msg);
  } else {
    console.error("Failed to add agent:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the agent was added successfully.
- **msg** (string) - A confirmation message (e.g., "agentAddedSuccessfully").
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Response Example
```json
{
  "ok": true,
  "msg": "agentAddedSuccessfully",
  "msgi18n": true
}
```

## Multi-Agent Management - Remove Agent

### Description
Removes a previously added remote Dockge agent.

### Method
`socket.emit`

### Endpoint
`removeAgent`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agentUrl** (string) - The URL of the agent to remove.

### Request Example
```javascript
socket.emit("removeAgent", "https://remote-dockge.example.com:5001", (response) => {
  if (response.ok) {
    console.log("Agent removed:", response.msg);
  } else {
    console.error("Failed to remove agent:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the agent was removed successfully.
- **msg** (string) - A confirmation message (e.g., "agentRemovedSuccessfully").
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Response Example
```json
{
  "ok": true,
  "msg": "agentRemovedSuccessfully",
  "msgi18n": true
}
```

## Multi-Agent Management - Update Agent

### Description
Updates the display name of a remote Dockge agent.

### Method
`socket.emit`

### Endpoint
`updateAgent`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agentUrl** (string) - The URL of the agent to update.
- **newName** (string) - The new display name for the agent.

### Request Example
```javascript
socket.emit("updateAgent", "https://remote-dockge.example.com:5001", "New Display Name", (response) => {
  if (response.ok) {
    console.log("Agent updated:", response.msg);
  } else {
    console.error("Failed to update agent:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the agent was updated successfully.
- **msg** (string) - A confirmation message.

#### Response Example
```json
{
  "ok": true,
  "msg": "Agent updated successfully"
}
```

## Multi-Agent - Agent List and Status Updates

### Description
Listeners for updates to the agent list and the status of individual agents.

### Method
`socket.on`

### Endpoint
`agentList`, `agentStatus`

### Parameters
None

### Request Example
```javascript
// Listen for agent list updates
socket.on("agentList", (data) => {
  console.log("Agent list:", data.agentList);
});

// Listen for agent status changes
socket.on("agentStatus", (data) => {
  console.log("Agent status:", data.endpoint, data.status);
});
```

### Response
#### Success Response (200)
- **agentList** (object) - A map of agent endpoints to their details.
- **endpoint** (string) - The endpoint of the agent whose status changed.
- **status** (string) - The new status of the agent (e.g., "connecting", "online", "offline").

#### Response Example
```json
{
  "agentList": {
    "": { "url": "", "endpoint": "", "name": "" },
    "remote-dockge.example.com:5001": {
      "url": "https://remote-dockge.example.com:5001",
      "endpoint": "remote-dockge.example.com:5001",
      "name": "Production Server"
    }
  }
}
```

## Multi-Agent - Operations on Remote Agents

### Description
Performs operations like deploying stacks or retrieving stack information from remote agents.

### Method
`socket.emit`

### Endpoint
`agent`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **endpoint** (string) - The endpoint of the remote agent.
- **event** (string) - The operation to perform (e.g., `deployStack`, `getStack`).
- **args** (any) - Arguments specific to the operation.

### Request Example
```javascript
const endpoint = "remote-dockge.example.com:5001";

// Deploy stack to a specific remote agent
socket.emit("agent", endpoint, "deployStack", "remote-stack", composeYAML, composeENV, true, (response) => {
  if (response.ok) {
    console.log("Stack deployed to remote agent");
  }
});

// Get stack from remote agent
socket.emit("agent", endpoint, "getStack", "remote-stack", (response) => {
  if (response.ok) {
    console.log("Remote stack:", response.stack);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **stack** (object, optional) - The stack information (for `getStack`).

#### Response Example
```json
{
  "ok": true,
  "stack": { ... }
}
```
```

--------------------------------

### Stack Management - Deploy New Stack

Source: https://context7.com/louislam/dockge/llms.txt

Deploys a new Docker Compose stack or updates an existing one.

```APIDOC
## Deploy New Stack

### Description
Deploys a new Docker Compose stack or updates an existing one.

### Method
SOCKET.EMIT

### Endpoint
`agent` with action `deployStack`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agent** (string) - Should be empty string `""`.
- **action** (string) - Must be `"deployStack"`.
- **stackName** (string) - Required - The name of the Docker Compose stack.
- **composeYAML** (string) - Required - The content of the `docker-compose.yaml` file.
- **composeENV** (string) - Optional - The content of the `.env` file for the stack.
- **isAdd** (boolean) - Required - `true` to deploy a new stack, `false` to update an existing one.

### Request Example
```javascript
const stackName = "my-nginx";
const composeYAML = `
services:
  nginx:
    image: nginx:latest
    ports:
      - "8080:80"
    restart: unless-stopped
`;
const composeENV = `
# Environment variables
NGINX_HOST=localhost
`;
const isAdd = true;

socket.emit("agent", "", "deployStack", stackName, composeYAML, composeENV, isAdd, (response) => {
  if (response.ok) {
    console.log("Stack deployed successfully:", response.msg);
  } else {
    console.error("Deployment failed:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the deployment was successful.
- **msg** (string) - Confirmation message, e.g., "Deployed".
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Failure Response
- **ok** (boolean) - Indicates if the deployment failed.
- **msg** (string) - Error message.

#### Response Example
```json
{
  "ok": true,
  "msg": "Deployed",
  "msgi18n": true
}
```
```

--------------------------------

### Composerize - Convert Docker Run to Compose

Source: https://context7.com/louislam/dockge/llms.txt

Converts a `docker run` command into a Docker Compose YAML format.

```APIDOC
## Composerize - Convert Docker Run to Compose

### Description
Converts a given `docker run` command string into a Docker Compose YAML configuration.

### Method
`socket.emit`

### Endpoint
`composerize`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **dockerRunCommand** (string) - The `docker run` command to convert.

### Request Example
```javascript
const dockerRunCommand = "docker run -d -p 8080:80 -v /data:/app/data --name my-app nginx:latest";

socket.emit("composerize", dockerRunCommand, (response) => {
  if (response.ok) {
    console.log("Compose template:", response.composeTemplate);
  } else {
    console.error("Conversion failed:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the conversion was successful.
- **composeTemplate** (string) - The generated Docker Compose YAML content.

#### Response Example
```json
{
  "ok": true,
  "composeTemplate": "services:\n  my-app:\n    image: nginx:latest\n    ports:\n      - \"8080:80\"\n    volumes:\n      - /data:/app/data"
}
```
```

--------------------------------

### Convert Docker Run to Compose

Source: https://context7.com/louislam/dockge/llms.txt

Convert a 'docker run' command into a Docker Compose YAML format. The response includes the generated 'composeTemplate'.

```javascript
// Convert docker run command to compose.yaml format
const dockerRunCommand = "docker run -d -p 8080:80 -v /data:/app/data --name my-app nginx:latest";

socket.emit("composerize", dockerRunCommand, (response) => {
  if (response.ok) {
    console.log("Compose template:", response.composeTemplate);
    // services:
    //   my-app:
    //     image: nginx:latest
    //     ports:
    //       - "8080:80"
    //     volumes:
    //       - /data:/app/data
  } else {
    console.error("Conversion failed:", response.msg);
  }
});
```

--------------------------------

### Settings Management

Source: https://context7.com/louislam/dockge/llms.txt

APIs for retrieving and updating application settings.

```APIDOC
## Settings - Get Settings

### Description
Retrieves the current application settings.

### Method
`socket.emit`

### Endpoint
`getSettings`

### Parameters
None

### Request Example
```javascript
socket.emit("getSettings", (response) => {
  if (response.ok) {
    console.log("Settings:", response.data);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the settings were retrieved successfully.
- **data** (object) - An object containing the application settings.
  - **disableAuth** (boolean) - Whether authentication is disabled.
  - **primaryHostname** (string) - The primary hostname for the application.
  - **globalENV** (string) - Global environment variables.

#### Response Example
```json
{
  "ok": true,
  "data": {
    "disableAuth": false,
    "primaryHostname": "localhost",
    "globalENV": "# VARIABLE=value #comment"
  }
}
```

## Settings - Update Settings

### Description
Updates the application settings. A `currentPassword` is required if authentication is enabled and being modified.

### Method
`socket.emit`

### Endpoint
`setSettings`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **newSettings** (object) - An object containing the new settings to apply.
  - **disableAuth** (boolean) - Whether to disable authentication.
  - **primaryHostname** (string) - The new primary hostname.
  - **globalENV** (string) - The new global environment variables.
- **currentPassword** (string, optional) - The current password, required if authentication settings are changed.

### Request Example
```javascript
const newSettings = {
  disableAuth: false,
  primaryHostname: "myserver.local",
  globalENV: "GLOBAL_VAR=value\nANOTHER_VAR=123"
};
const currentPassword = "MyPassword123!";  // Required when enabling auth

socket.emit("setSettings", newSettings, currentPassword, (response) => {
  if (response.ok) {
    console.log("Settings saved:", response.msg);
  } else {
    console.error("Failed to save settings:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the settings were saved successfully.
- **msg** (string) - A confirmation message.

#### Response Example
```json
{
  "ok": true,
  "msg": "Saved"
}
```
```

--------------------------------

### Join and Leave Terminals

Source: https://context7.com/louislam/dockge/llms.txt

Use these methods to join a combined terminal to receive output or to leave it. Resizing is also supported.

```javascript
// Join terminal to receive output buffer
socket.emit("agent", "", "terminalJoin", "combined--my-stack", (response) => {
  if (response.ok) {
    console.log("Joined terminal, buffer:", response.buffer);
  }
});

// Leave combined terminal
socket.emit("agent", "", "leaveCombinedTerminal", "my-stack", (response) => {
  if (response.ok) {
    console.log("Left combined terminal");
  }
});

// Resize terminal
socket.emit("agent", "", "terminalResize", "console", 50, 120);
```

--------------------------------

### Stack Management - Update Stack (Pull & Restart)

Source: https://context7.com/louislam/dockge/llms.txt

Pulls the latest Docker images for a stack and restarts it.

```APIDOC
## Update Stack (Pull & Restart)

### Description
Pulls the latest Docker images for a stack and restarts it.

### Method
SOCKET.EMIT

### Endpoint
`agent` with action `updateStack`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **agent** (string) - Should be empty string `""`.
- **action** (string) - Must be `"updateStack"`.
- **stackName** (string) - Required - The name of the stack to update.

### Request Example
```javascript
socket.emit("agent", "", "updateStack", "my-nginx", (response) => {
  if (response.ok) {
    console.log("Stack updated:", response.msg);
  } else {
    console.error("Failed to update stack:", response.msg);
  }
});
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the stack was updated successfully.
- **msg** (string) - Confirmation message, e.g., "Updated".
- **msgi18n** (boolean) - Indicates if the message is internationalized.

#### Failure Response
- **ok** (boolean) - Indicates if updating the stack failed.
- **msg** (string) - Error message.

#### Response Example
```json
{
  "ok": true,
  "msg": "Updated",
  "msgi18n": true
}
```
```