ZaneOps

https://github.com/zane-ops/zane-ops
Admin
ZaneOps is a beautiful, self-hosted, open-source platform for deploying static sites, web apps,...
Tokens:47,015
Snippets:415
Trust Score:8.1
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run setup script

Source: https://github.com/zane-ops/zane-ops/blob/main/CONTRIBUTING.md

Initializes the development environment.

```shell
make setup
```

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

### Install Project Dependencies

Source: https://github.com/zane-ops/zane-ops/blob/main/frontend/README.md

Run this command in your terminal to install all necessary project dependencies.

```bash
npm install
```

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

### Valid Route Configuration Example

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

A minimal valid configuration for a route, requiring at least a domain and a port. This serves as a basic example for successful route setup.

```yaml
zane.http.routes.0.domain: "example.com"
zane.http.routes.0.port: "80"
```

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

### Start development server

Source: https://github.com/zane-ops/zane-ops/blob/main/CONTRIBUTING.md

Commands to launch the development environment.

```shell
make dev
# or
pnpm run --recursive --parallel dev
```

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

### GET /api/github/apps/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Lists configured GitHub App installations.

```APIDOC
## GET /api/github/apps/

### Description
Lists configured GitHub App installations for repository access.

### Method
GET

### Endpoint
/api/github/apps/

### Response
#### Success Response (200)
- **id** (string) - App ID
- **name** (string) - App name
- **installation_id** (string) - GitHub installation ID
```

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

### Initialize Project

Source: https://github.com/zane-ops/zane-ops/blob/main/CLAUDE.md

Initializes Docker Swarm, creates the overlay network, and installs dependencies.

```bash
# Clone and setup the project
make setup
```

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

### Install ZaneOps

Source: https://github.com/zane-ops/zane-ops/blob/main/README.md

Use this command to install ZaneOps. Ensure you have curl and sudo privileges.

```shell
curl -fsSL https://cdn.zaneops.dev/install.sh | sudo bash
```

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

### Run Development Servers

Source: https://github.com/zane-ops/zane-ops/blob/main/CLAUDE.md

Commands to start the development environment and apply database migrations.

```bash
# Start all services (frontend + backend + dependencies)
make dev

# Start only backend services (excluding frontend)
make dev-api

# After starting, run migrations
make migrate
```

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

### Get Project Details

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Fetches detailed configuration for a specific project by slug.

```bash
curl -X GET "https://your-zaneops-instance.com/api/projects/my-webapp/" \
  -b cookies.txt

# Response (200 OK)
{
  "id": "prj_abc123xyz",
  "slug": "my-webapp",
  "description": "My production web application",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "environments": [
    {"id": "env_prod123", "name": "production", "is_preview": false}
  ]
}
```

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

### List Repositories

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Lists repositories accessible via a specific GitHub App installation.

```bash
curl -X GET "https://your-zaneops-instance.com/api/github/apps/gh_app123/repos/" \
  -b cookies.txt
```

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

### List GitHub Apps

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Lists configured GitHub App installations for repository access.

```bash
curl -X GET "https://your-zaneops-instance.com/api/github/apps/" \
  -b cookies.txt
```

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

### GET /api/github/apps/{app_id}/repos/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Lists repositories accessible via a GitHub App installation.

```APIDOC
## GET /api/github/apps/{app_id}/repos/

### Description
Lists repositories accessible via a GitHub App installation.

### Method
GET

### Endpoint
/api/github/apps/{app_id}/repos/

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The GitHub App ID

### Response
#### Success Response (200)
- **repositories** (array) - List of repository objects
```

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

### Dokploy Template Configuration Format

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/docker-compose.md

Example of the TOML configuration format used by the Dokploy template adapter.

```toml
[variables]
main_domain = "${domain}"
db_password = "${password:32}"

[[config.domains]]
serviceName = "web"
port = 8080
host = "${main_domain}"

[config.env]
DB_PASSWORD = "${db_password}"

[[config.mounts]]
filePath = "./nginx.conf"
content = "..."
```

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

### Start Development Server

Source: https://github.com/zane-ops/zane-ops/blob/main/frontend/README.md

Initiates the development server with Hot Module Replacement (HMR) enabled for rapid development cycles. The application will be accessible at http://localhost:5173.

```bash
npm run dev
```

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

### Get Build Logs

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves build output logs for specific Git service deployments using a GET request.

```bash
curl -X GET "https://your-zaneops-instance.com/api/projects/my-webapp/services/frontend/deployments/dpl_build789/build-logs/production/" \
  -b cookies.txt
```

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

### Get Deployment Details

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves detailed information about a specific deployment, including the full service snapshot configuration. Requires the deployment hash.

```bash
curl -X GET "https://your-zaneops-instance.com/api/projects/my-webapp/services/api-server/deployments/dpl_latest123/production/" \
  -b cookies.txt
```

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

### Template Expression Generation Example

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/docker-compose.md

Illustrates the process of generating and saving environment variable overrides for template expressions found in a compose file.

```python
# Generate value and save as override
generated_value = ComposeProcessor.generate_template_value(template_func)
stack.env_overrides.create(
    key=key,
    value=generated_value,
    service_name=service_name,
    is_generated=True
)
```

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

### GET /api/projects/{project_id}/services/{service_id}/deployments/{deployment_id}/build-logs/{environment}/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves build output logs for specific Git service deployments.

```APIDOC
## GET /api/projects/{project_id}/services/{service_id}/deployments/{deployment_id}/build-logs/{environment}/

### Description
Retrieves build output logs for Git service deployments.

### Method
GET

### Endpoint
/api/projects/{project_id}/services/{service_id}/deployments/{deployment_id}/build-logs/{environment}/

### Response
#### Success Response (200)
- **results** (array) - List of log entries containing time, level, content, and source.
```

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

### GET /api/projects/{project}/envs/{env}/variables/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

List all shared environment variables for a specific project environment.

```APIDOC
## GET /api/projects/{project}/envs/{env}/variables/

### Description
Retrieves a list of environment-level variables available to all services in the specified environment.

### Method
GET

### Endpoint
/api/projects/{project}/envs/{env}/variables/

### Parameters
#### Path Parameters
- **project** (string) - Required - The project identifier
- **env** (string) - Required - The environment name
```

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

### Manage Docker Stack Services

Source: https://github.com/zane-ops/zane-ops/blob/main/CLAUDE.md

Scripts to start and stop the Docker Swarm services used in development.

```bash
cd docker
./start-docker-stack.sh
./stop-docker-stack.sh
```

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

### Create New Project

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Initializes a project with a production environment and default preview template.

```bash
curl -X POST "https://your-zaneops-instance.com/api/projects/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "slug": "my-webapp",
    "description": "My production web application"
  }'

# Response (201 Created)
{
  "id": "prj_abc123xyz",
  "slug": "my-webapp",
  "description": "My production web application",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "environments": [
    {
      "id": "env_prod123",
      "name": "production",
      "is_preview": false
    }
  ],
  "healthy_services": 0,
  "total_services": 0
}
```

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

### Create Environment

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Initializes a new empty environment within a project.

```bash
curl -X POST "https://your-zaneops-instance.com/api/projects/my-webapp/envs/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "staging"
  }'
```

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

### Deploy Application with External Config Files

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Demonstrates mounting configuration files into services using the configs block.

```yaml
x-zane-env:
  APP_NAME: "{{ generate_slug }}"
  DB_HOST: "{{ network_alias | 'postgres' }}"

services:
  web:
    image: nginx:alpine
    configs:
      - source: nginx_config
        target: /etc/nginx/nginx.conf
      - source: app_config
        target: /etc/app/config.json
    deploy:
      labels:
        zane.http.routes.0.domain: "example.com"
        zane.http.routes.0.port: "80"

configs:
  nginx_config:
    content: |
      user nginx;
      worker_processes auto;

      events {
        worker_connections 1024;
      }

      http {
        server {
          listen 80;
          server_name example.com;

          location / {
            root /usr/share/nginx/html;
            index index.html;
          }
        }
      }

  app_config:
    content: |
      {
        "app_name": "${APP_NAME}",
        "database": {
          "host": "${DB_HOST}",
          "port": 5432
        }
      }
```

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

### Deploy a Simple Web Application

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Configures a basic Nginx service with HTTP routing labels for domain and port mapping.

```yaml
services:
  web:
    image: nginx:alpine
    deploy:
      replicas: 2
      labels:
        zane.http.routes.0.domain: "myapp.com"
        zane.http.routes.0.port: "80"
        zane.http.routes.0.base_path: "/"
        zane.http.routes.0.strip_prefix: "false"
```

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

### GET /api/logs/http/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves HTTP request logs with filtering options.

```APIDOC
## GET /api/logs/http/

### Description
Retrieves HTTP request logs with filtering by method, status, path, and time range.

### Method
GET

### Endpoint
/api/logs/http/

### Parameters
#### Query Parameters
- **service_id** (string) - Optional - Filter by service ID
- **status** (integer) - Optional - Filter by HTTP status code
- **per_page** (integer) - Optional - Number of results per page

### Response
#### Success Response (200)
- **count** (integer) - Total number of logs
- **next** (string) - Cursor token for pagination
- **results** (array) - List of HTTP log objects
```

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

### Database Initialization Scripts

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Includes SQL initialization scripts as configs that are mounted into the database container's entrypoint directory. This ensures the database schema is set up on the first startup.

```yaml
services:
  postgres:
    image: postgres:16
    configs:
      - source: init_sql
        target: /docker-entrypoint-initdb.d/init.sql

configs:
  init_sql:
    content: |
      CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
      CREATE TABLE users (
        id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
        email TEXT UNIQUE NOT NULL
      );
```

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

### Define Multi-Service Stack

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/docker-compose.md

Example of a WordPress stack with a database service that is not exposed to the internet.

```yaml
version: "3.8"

services:
  wordpress:
    image: wordpress:latest
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
    networks:
      - zane
    volumes:
      - wordpress_data:/var/www/html
    deploy:
      labels:
        zane.http.port: "80"
        zane.http.routes.0.domain: "myblog.example.com"
        zane.http.routes.0.base_path: "/"

  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: wordpress
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    networks:
      - zane
    volumes:
      - db_data:/var/lib/mysql
    # No zane.http.port - database not exposed to internet

volumes:
  wordpress_data:
  db_data:

networks:
  zane:
    external: true
```

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

### Clone the repository

Source: https://github.com/zane-ops/zane-ops/blob/main/CONTRIBUTING.md

Initial step to download the project source code.

```shell
git clone https://github.com/zane-ops/zane-ops.git
```

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

### Toggle Compose Stack Services

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Stops or starts all services (or a specific service) in a compose stack.

```APIDOC
## PUT /api/compose/stacks/{project_slug}/{environment_name}/{stack_name}/toggle/

### Description
Stops or starts all services (or a specific service) in a compose stack.

### Method
PUT

### Endpoint
/api/compose/stacks/{project_slug}/{environment_name}/{stack_name}/toggle/

### Parameters
#### Path Parameters
- **project_slug** (string) - Required - The slug of the project.
- **environment_name** (string) - Required - The name of the environment.
- **stack_name** (string) - Required - The name of the stack.

### Request Body
- **desired_state** (string) - Required - The desired state for the services (e.g., "SLEEPING").
- **service_name** (string) - Optional - The name of a specific service to toggle. If not provided, all services in the stack are affected.

### Request Example
```json
{
  "desired_state": "SLEEPING",
  "service_name": "grafana"
}
```

### Response
#### Success Response (202 Accepted)
This endpoint returns a 202 Accepted status upon successful request, indicating the state change has been initiated.
```

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

### Docker Build and Run

Source: https://github.com/zane-ops/zane-ops/blob/main/frontend/README.md

Commands to build a Docker image for the application and run it as a container. Supports different package managers (npm, pnpm, bun) via separate Dockerfiles.

```bash
# For npm
docker build -t my-app .

# For pnpm
docker build -f Dockerfile.pnpm -t my-app .

# For bun
docker build -f Dockerfile.bun -t my-app .

# Run the container
docker run -p 3000:3000 my-app
```

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

### Get Runtime Logs

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves application runtime logs from a deployment with filtering and pagination via cursor.

```APIDOC
## GET /api/projects/{project_slug}/services/{service_slug}/deployments/{deployment_hash}/logs/{environment_name}/

### Description
Retrieves application runtime logs from a deployment with filtering and pagination via cursor.

### Method
GET

### Endpoint
/api/projects/{project_slug}/services/{service_slug}/deployments/{deployment_hash}/logs/{environment_name}/

### Parameters
#### Path Parameters
- **project_slug** (string) - Required - The slug of the project.
- **service_slug** (string) - Required - The slug of the service.
- **deployment_hash** (string) - Required - The hash of the deployment.
- **environment_name** (string) - Required - The name of the environment.

#### Query Parameters
- **level** (string) - Optional - Filter logs by level (e.g., "ERROR").
- **limit** (integer) - Optional - The maximum number of log entries to return.

### Response
#### Success Response (200 OK)
This endpoint returns the log entries. The exact structure of the log entries is not detailed in the provided text, but typically includes timestamp, log level, and message.
```

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

### Get Deployment Details

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves detailed information about a specific deployment including the full service snapshot.

```APIDOC
## GET /api/projects/{project_slug}/services/{service_slug}/deployments/{deployment_hash}/{environment_name}/

### Description
Retrieves detailed information about a specific deployment including the full service snapshot.

### Method
GET

### Endpoint
/api/projects/{project_slug}/services/{service_slug}/deployments/{deployment_hash}/{environment_name}/

### Parameters
#### Path Parameters
- **project_slug** (string) - Required - The slug of the project.
- **service_slug** (string) - Required - The slug of the service.
- **deployment_hash** (string) - Required - The hash of the deployment.
- **environment_name** (string) - Required - The name of the environment.

### Response
#### Success Response (200 OK)
- **hash** (string) - The unique identifier for the deployment.
- **status** (string) - The status of the deployment.
- **is_current_production** (boolean) - Indicates if this is the current production deployment.
- **queued_at** (string) - Timestamp when the deployment was queued.
- **started_at** (string) - Timestamp when the deployment started.
- **finished_at** (string) - Timestamp when the deployment finished.
- **commit_message** (string) - The commit message associated with the deployment.
- **service_snapshot** (object) - The snapshot of the service configuration for this deployment.
  - **image** (string) - The Docker image used for the service.
  - **urls** (array) - List of URLs associated with the service.
    - **domain** (string) - The domain name.
    - **base_path** (string) - The base path for the URL.
  - **env_variables** (array) - Environment variables for the service.
    - **key** (string) - The environment variable key.
    - **value** (string) - The environment variable value.
  - **volumes** (array) - Volumes mounted by the service.
    - **container_path** (string) - The path within the container.
    - **mode** (string) - The volume mode (e.g., "READ_WRITE").
  - **healthcheck** (object) - Health check configuration for the service.
    - **type** (string) - The type of health check (e.g., "PATH").
    - **value** (string) - The value for the health check (e.g., a URL path).

#### Response Example
```json
{
  "hash": "dpl_latest123",
  "status": "HEALTHY",
  "is_current_production": true,
  "queued_at": "2024-01-15T10:35:00Z",
  "started_at": "2024-01-15T10:35:05Z",
  "finished_at": "2024-01-15T10:36:30Z",
  "commit_message": "Deploy v2.0.0",
  "service_snapshot": {
    "image": "myregistry.com/myapp:v2.0.0",
    "urls": [{"domain": "api.example.com", "base_path": "/"}],
    "env_variables": [{"key": "NODE_ENV", "value": "production"}],
    "volumes": [{"container_path": "/data", "mode": "READ_WRITE"}],
    "healthcheck": {"type": "PATH", "value": "/health"}
  }
}
```
```

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

### POST /api/compose/stacks/{project}/{env}/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Create a new compose stack.

```APIDOC
## POST /api/compose/stacks/{project}/{env}/

### Description
Initializes a new compose stack for a project environment.

### Method
POST

### Endpoint
/api/compose/stacks/{project}/{env}/

### Parameters
#### Request Body
- **slug** (string) - Required - The stack identifier

### Response
#### Success Response (201)
- **id** (string) - Stack ID
- **slug** (string) - Stack slug
- **deploy_token** (string) - Token for deployment
```

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

### Projects API - Get Single Project

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves detailed information about a specific project using its slug.

```APIDOC
## GET /api/projects/{slug}/

### Description
Retrieves detailed information about a specific project.

### Method
GET

### Endpoint
/api/projects/{slug}/

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the project to retrieve.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the project.
- **slug** (string) - The slug of the project.
- **description** (string) - The description of the project.
- **created_at** (string) - The timestamp when the project was created.
- **updated_at** (string) - The timestamp when the project was last updated.
- **environments** (array) - A list of environments associated with the project.
  - **id** (string) - The environment ID.
  - **name** (string) - The environment name.
  - **is_preview** (boolean) - Indicates if the environment is a preview environment.

#### Response Example
```json
{
  "id": "prj_abc123xyz",
  "slug": "my-webapp",
  "description": "My production web application",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "environments": [
    {"id": "env_prod123", "name": "production", "is_preview": false}
  ]
}
```
```

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

### POST /api/compose/stacks/{project}/{env}/from-dokploy/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Create a compose stack from a Dokploy template.

```APIDOC
## POST /api/compose/stacks/{project}/{env}/from-dokploy/

### Description
Creates a compose stack using a base64 encoded Dokploy template.

### Method
POST

### Endpoint
/api/compose/stacks/{project}/{env}/from-dokploy/

### Parameters
#### Request Body
- **slug** (string) - Required - The stack slug
- **user_content** (string) - Required - Base64 encoded template
```

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

### Configure Service Deployment and Environment

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/docker-compose.md

Injects network settings, rolling update configurations, and merges environment variables from multiple sources into a service specification.

```python
service.networks.append("zane")
            elif isinstance(service.networks, dict):
                if "zane" not in service.networks:
                    service.networks["zane"] = None
            else:
                # No networks specified - add zane
                service.networks = ["zane"]

            # 2. Inject safe update_config for rolling updates
            if not service.deploy:
                service.deploy = {}

            if "update_config" not in service.deploy:
                service.deploy["update_config"] = {
                    "parallelism": 1,
                    "delay": "5s",
                    "order": "start-first",
                    "failure_action": "rollback"
                }

            # 3. Merge environment variable overrides
            env_dict = {}

            # First, add env vars from compose file
            if isinstance(service.environment, list):
                for env_var in service.environment:
                    if isinstance(env_var, str):
                        if "=" in env_var:
                            key, value = env_var.split("=", 1)
                            env_dict[key] = value
                        else:
                            # Variable without value - keep as-is
                            env_dict[env_var] = ""
            elif isinstance(service.environment, dict):
                env_dict.update(service.environment)

            # Then, apply service-specific overrides (includes generated values)
            service_overrides = env_overrides.get(service_name, {})
            env_dict.update(service_overrides)

            # Apply stack-level overrides (overrides for all services)
            stack_level_overrides = env_overrides.get(None, {})
            env_dict.update(stack_level_overrides)

            # Convert back to dict format (Docker Swarm prefers dict over list)
            service.environment = env_dict
```

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

### Get HTTP Logs

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves filtered HTTP request logs. Supports filtering by method, status, path, and time range.

```bash
curl -X GET "https://your-zaneops-instance.com/api/logs/http/?service_id=srv_api123xyz&status=500&status=502&per_page=50" \
  -b cookies.txt
```

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

### POST /api/projects/{project_id}/envs/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Creates a new, empty environment within a project. Environments serve as isolated deployment contexts.

```APIDOC
## POST /api/projects/{project_id}/envs/

### Description
Creates a new empty environment within a project.

### Method
POST

### Endpoint
`/api/projects/{project_id}/envs/`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Request Body
- **name** (string) - Required - The name for the new environment (e.g., 'staging').

### Request Example
```json
{
  "name": "staging"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique ID of the created environment.
- **name** (string) - The name of the environment.
- **is_preview** (boolean) - Flag indicating if it's a preview environment.
- **variables** (array) - A list of environment variables.

#### Response Example
```json
{
  "id": "env_staging789",
  "name": "staging",
  "is_preview": false,
  "variables": []
}
```
```

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

### Authentication API - Get Current User

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves the currently authenticated user's profile information using the session cookie.

```APIDOC
## GET /api/auth/me/

### Description
Retrieves the currently authenticated user's profile information.

### Method
GET

### Endpoint
/api/auth/me/

### Parameters
#### Query Parameters
- **cookies.txt** (cookie) - Required - Session cookie obtained after login.

### Response
#### Success Response (200 OK)
- **username** (string) - The username of the authenticated user.
- **first_name** (string) - The first name of the authenticated user.
- **last_name** (string) - The last name of the authenticated user.

#### Response Example
```json
{
  "username": "admin",
  "first_name": "Admin",
  "last_name": "User"
}
```
```

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

### Docker swarm error message

Source: https://github.com/zane-ops/zane-ops/blob/main/CONTRIBUTING.md

A common error message encountered during setup that can be safely ignored if Docker swarm is already initialized.

```text
Error response from daemon: This node is already part of a swarm. Use "docker swarm leave" to leave this swarm and join another one.
```

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

### Run database migrations

Source: https://github.com/zane-ops/zane-ops/blob/main/CONTRIBUTING.md

Applies necessary database schema changes.

```shell
make migrate
```

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

### Projects API - Create Project

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Creates a new project with a production environment and a default preview template.

```APIDOC
## POST /api/projects/

### Description
Creates a new project with a production environment and default preview template automatically generated.

### Method
POST

### Endpoint
/api/projects/

### Parameters
#### Request Body
- **slug** (string) - Required - A unique identifier for the project.
- **description** (string) - Optional - A description for the project.

### Request Example
```json
{
  "slug": "my-webapp",
  "description": "My production web application"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created project.
- **slug** (string) - The slug of the created project.
- **description** (string) - The description of the created project.
- **created_at** (string) - The timestamp when the project was created.
- **updated_at** (string) - The timestamp when the project was last updated.
- **environments** (array) - A list of environments associated with the project.
  - **id** (string) - The environment ID.
  - **name** (string) - The environment name.
  - **is_preview** (boolean) - Indicates if the environment is a preview environment.
- **healthy_services** (integer) - The number of healthy services in the project.
- **total_services** (integer) - The total number of services in the project.

#### Response Example
```json
{
  "id": "prj_abc123xyz",
  "slug": "my-webapp",
  "description": "My production web application",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "environments": [
    {
      "id": "env_prod123",
      "name": "production",
      "is_preview": false
    }
  ],
  "healthy_services": 0,
  "total_services": 0
}
```
```

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

### Authentication API - Create Initial User

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Creates the first admin user in a fresh ZaneOps installation. This endpoint is only available when no users exist.

```APIDOC
## POST /api/auth/create-initial-user/

### Description
Creates the first admin user in a fresh ZaneOps installation. Only works when no users exist in the system.

### Method
POST

### Endpoint
/api/auth/create-initial-user/

### Request Body
- **username** (string) - Required - The desired username for the admin user.
- **password** (string) - Required - The password for the admin user.
- **first_name** (string) - Required - The first name of the admin user.
- **last_name** (string) - Required - The last name of the admin user.

### Request Example
```json
{
  "username": "admin",
  "password": "your-secure-password",
  "first_name": "Admin",
  "last_name": "User"
}
```

### Response
#### Success Response (201 Created)
- **username** (string) - The username of the created user.
- **first_name** (string) - The first name of the created user.
- **last_name** (string) - The last name of the created user.

#### Response Example
```json
{
  "username": "admin",
  "first_name": "Admin",
  "last_name": "User"
}
```
```

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

### PUT /api/compose/stacks/{project}/{env}/{stack}/deploy/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Deploy a compose stack.

```APIDOC
## PUT /api/compose/stacks/{project}/{env}/{stack}/deploy/

### Description
Deploys the compose stack with all pending changes applied.

### Method
PUT

### Endpoint
/api/compose/stacks/{project}/{env}/{stack}/deploy/

### Parameters
#### Request Body
- **commit_message** (string) - Optional - Message describing the deployment
```

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

### Build for Production

Source: https://github.com/zane-ops/zane-ops/blob/main/frontend/README.md

Generates a production-ready build of the application, optimizing assets and code for deployment.

```bash
npm run build
```

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

### List All Projects

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves a list of all projects associated with the authenticated user.

```bash
curl -X GET "https://your-zaneops-instance.com/api/projects/" \
  -b cookies.txt

# Response (200 OK)
[
  {
    "id": "prj_abc123xyz",
    "slug": "my-webapp",
    "description": "My production web application",
    "healthy_services": 3,
    "total_services": 4,
    "environments": [
      {"id": "env_prod123", "name": "production", "is_preview": false},
      {"id": "env_staging456", "name": "staging", "is_preview": false}
    ]
  }
]
```

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

### Toggle Compose Stack Services State

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Stops or starts all services, or a specific service, within a compose stack. Ensure you have the correct cookies for authentication.

```bash
# Stop entire stack
curl -X PUT "https://your-zaneops-instance.com/api/compose/stacks/my-webapp/production/monitoring/toggle/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ 
    "desired_state": "SLEEPING"
  }'
```

```bash
# Stop only grafana service
curl -X PUT "https://your-zaneops-instance.com/api/compose/stacks/my-webapp/production/monitoring/toggle/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ 
    "desired_state": "SLEEPING",
    "service_name": "grafana"
  }'
```

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

### Service Dependencies

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Control startup order using depends_on, noting that ZaneOps converts dict formats to lists for Swarm compatibility.

```yaml
services:
  app:
    image: myapp:latest
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16

  redis:
    image: redis:alpine
```

```yaml
services:
  app:
    depends_on:
      postgres:
        condition: service_healthy
```

```yaml
services:
  app:
    depends_on:
      - postgres
```

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

### POST /api/projects/{project_id}/envs/{source_env_name}/clone/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Clones an existing environment to create a new one. Optionally deploys services immediately after cloning.

```APIDOC
## POST /api/projects/{project_id}/envs/{source_env_name}/clone/

### Description
Creates a new environment by cloning all services from an existing environment, optionally deploying immediately.

### Method
POST

### Endpoint
`/api/projects/{project_id}/envs/{source_env_name}/clone/`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **source_env_name** (string) - Required - The name of the environment to clone from.

#### Request Body
- **name** (string) - Required - The name for the new cloned environment.
- **deploy_after_clone** (boolean) - Optional - If true, deploys services immediately after cloning.

### Request Example
```json
{
  "name": "staging",
  "deploy_after_clone": true
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique ID of the cloned environment.
- **name** (string) - The name of the cloned environment.
- **is_preview** (boolean) - Flag indicating if it's a preview environment.
- **variables** (array) - A list of environment variables.

#### Response Example
```json
{
  "id": "env_staging789",
  "name": "staging",
  "is_preview": false,
  "variables": []
}
```
```

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

### POST /api/projects/{project}/envs/{env}/variables/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Create a new shared environment variable.

```APIDOC
## POST /api/projects/{project}/envs/{env}/variables/

### Description
Creates a new environment variable for the specified project environment.

### Method
POST

### Endpoint
/api/projects/{project}/envs/{env}/variables/

### Parameters
#### Request Body
- **key** (string) - Required - The variable name
- **value** (string) - Required - The variable value
```

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

### ZaneOps API for Registry Authentication

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Example HTTP POST request to the ZaneOps API for configuring container registry credentials. This enables pulling private images during stack deployment.

```http
POST /api/container-registries/
Content-Type: application/json

{
  "url": "https://index.docker.io/v1/",
  "username": "myuser",
  "password": "mytoken"
}
```

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

### Get Runtime Logs for a Deployment

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Retrieves application runtime logs for a specific deployment. Supports filtering by log level and limiting the number of log entries returned using a cursor for pagination.

```bash
curl -X GET "https://your-zaneops-instance.com/api/projects/my-webapp/services/api-server/deployments/dpl_latest123/logs/production/?level=ERROR&limit=100" \
  -b cookies.txt
```

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

### POST /api/preview/{project_id}/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Triggers the creation of a preview environment, typically from a pull request or a specific branch. Useful for CI/CD integrations.

```APIDOC
## POST /api/preview/{project_id}/

### Description
Creates a preview environment from a pull request or branch. Typically called via webhook from Git providers.

### Method
POST

### Endpoint
`/api/preview/{project_id}/`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Request Body
*Either `pr_number` or `branch_name` must be provided.*
- **pr_number** (integer) - Optional - The pull request number to create a preview environment from.
- **branch_name** (string) - Optional - The branch name to create a preview environment from.
- **commit_sha** (string) - Optional - The commit SHA associated with the branch or PR.
- **template** (string) - Optional - The environment template to use.
- **env_variables** (array) - Optional - A list of environment variables to set for the preview environment.
  - **key** (string) - Required - The environment variable key.
  - **value** (string) - Required - The environment variable value.

### Request Example (from PR)
```json
{
  "pr_number": 42,
  "template": "default-preview",
  "env_variables": [
    {"key": "DEBUG", "value": "true"}
  ]
}
```

### Request Example (from Branch)
```json
{
  "branch_name": "feature/new-ui",
  "commit_sha": "abc123def456",
  "template": "default-preview"
}
```

### Response
(No specific response details provided in the source for this endpoint.)
```

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

### Invalid Route Configurations

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Examples of invalid route configurations that will fail ZaneOps validation. These include missing required properties like domain or port, and incorrect value types for port or strip_prefix.

```yaml
# Missing domain
zane.http.routes.0.port: "80"
```

```yaml
# Missing port
zane.http.routes.0.domain: "example.com"
```

```yaml
# Invalid port
zane.http.routes.0.domain: "example.com"
zane.http.routes.0.port: "not-a-number"
```

```yaml
# Invalid strip_prefix
zane.http.routes.0.domain: "example.com"
zane.http.routes.0.port: "80"
zane.http.routes.0.strip_prefix: "yes"  # Must be "true" or "false"
```

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

### Manage Inline Configurations

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/compose-template-guide.md

Use for small configuration files under 100 lines to enable version control and automatic versioning.

```yaml
# ✅ Good for configs < 100 lines
configs:
  nginx_config:
    content: |
      ...
```

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

### Frontend Development Commands

Source: https://github.com/zane-ops/zane-ops/blob/main/CLAUDE.md

Commands for managing the React and Vite frontend application.

```bash
cd frontend

# Generate API client from OpenAPI schema
pnpm generate:api

# Run dev server
pnpm dev

# Build for production
pnpm build

# Type checking
pnpm typecheck
```

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

### Get Docker Stack Service Statuses Helper

Source: https://github.com/zane-ops/zane-ops/blob/main/backend/notes/docker-compose.md

Internal helper method to query Docker stack services and return their statuses. It parses the JSON output from `docker stack services` to extract running and desired replica counts for each service.

```python
    async def _get_stack_service_statuses(self, stack_name: str) -> Dict[str, Dict]:
        """Query: docker stack services <stack_name> --format json"""
        result = subprocess.run(
            ["docker", "stack", "services", stack_name, "--format", "{{json .}}"],
            capture_output=True,
            text=True
        )

        service_statuses = {}
        for line in result.stdout.strip().split('\n'):
            if not line:
                continue

            svc = json.loads(line)
            service_name = svc["Name"].replace(f"{stack_name}_", "")
            replicas_str = svc.get("Replicas", "0/0")
            running, desired = map(int, replicas_str.split('/'))

            service_statuses[service_name] = {
                "status": "running" if running >= desired else "starting",
                "desired_replicas": desired,
                "running_replicas": running,
                "updated_at": timezone.now().isoformat(),
            }

        return service_statuses
```

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

### Create Compose Stack

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Initializes a new compose stack for a project environment.

```bash
curl -X POST "https://your-zaneops-instance.com/api/compose/stacks/my-webapp/production/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "slug": "monitoring"
  }'
```

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

### Create Git Service

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Creates a service that builds from a Git repository using various builders like Dockerfile or Nixpacks.

```bash
curl -X POST "https://your-zaneops-instance.com/api/projects/my-webapp/services/git/production/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "slug": "frontend",
    "repository_url": "https://github.com/myorg/frontend.git",
    "branch_name": "main",
    "builder": "DOCKERFILE",
    "dockerfile_path": "./Dockerfile",
    "build_context_dir": "."
  }'
```

```bash
curl -X POST "https://your-zaneops-instance.com/api/projects/my-webapp/services/git/production/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "slug": "api",
    "repository_url": "https://github.com/myorg/api.git",
    "branch_name": "main",
    "builder": "NIXPACKS",
    "build_directory": ".",
    "custom_start_command": "node server.js"
  }'
```

```bash
curl -X POST "https://your-zaneops-instance.com/api/projects/my-webapp/services/git/production/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "slug": "docs",
    "repository_url": "https://github.com/myorg/docs.git",
    "branch_name": "main",
    "builder": "NIXPACKS",
    "build_directory": ".",
    "custom_build_command": "npm run build",
    "is_static": true,
    "publish_directory": "./dist",
    "is_spa": true,
    "index_page": "index.html"
  }'
```

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

### Trigger Preview Environment

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Creates a preview environment based on a pull request or branch.

```bash
curl -X POST "https://your-zaneops-instance.com/api/preview/a1b2c3d4e5f6g7h8/" \
  -H "Content-Type: application/json" \
  -d '{
    "pr_number": 42,
    "template": "default-preview",
    "env_variables": [
      {"key": "DEBUG", "value": "true"}
    ]
  }'
```

```bash
curl -X POST "https://your-zaneops-instance.com/api/preview/a1b2c3d4e5f6g7h8/" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_name": "feature/new-ui",
    "commit_sha": "abc123def456",
    "template": "default-preview"
  }'
```

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

### POST /api/projects/{project_id}/services/git/{environment}/

Source: https://context7.com/zane-ops/zane-ops/llms.txt

Creates a new Git service within a project for a specified environment. Supports various builders like Dockerfile, Nixpacks, and static site configurations.

```APIDOC
## POST /api/projects/{project_id}/services/git/{environment}/

### Description
Creates a service that builds from a Git repository using Dockerfile, Nixpacks, Railpack, or static directory builders.

### Method
POST

### Endpoint
`/api/projects/{project_id}/services/git/{environment}/`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **environment** (string) - Required - The target environment (e.g., 'production').

#### Request Body
- **slug** (string) - Required - A unique identifier for the service.
- **repository_url** (string) - Required - The URL of the Git repository.
- **branch_name** (string) - Required - The branch to build from.
- **builder** (string) - Required - The build tool to use (e.g., 'DOCKERFILE', 'NIXPACKS').
- **dockerfile_path** (string) - Optional - Path to the Dockerfile if using DOCKERFILE builder.
- **build_context_dir** (string) - Optional - The build context directory if using DOCKERFILE builder.
- **build_directory** (string) - Optional - The directory containing the application code if using Nixpacks.
- **custom_start_command** (string) - Optional - Custom command to start the application if using Nixpacks.
- **custom_build_command** (string) - Optional - Custom build command for static sites.
- **is_static** (boolean) - Optional - Flag indicating if it's a static site.
- **publish_directory** (string) - Optional - Directory to publish static site assets.
- **is_spa** (boolean) - Optional - Flag indicating if it's a Single Page Application.
- **index_page** (string) - Optional - The index page for SPA.

### Request Example
```json
{
  "slug": "frontend",
  "repository_url": "https://github.com/myorg/frontend.git",
  "branch_name": "main",
  "builder": "DOCKERFILE",
  "dockerfile_path": "./Dockerfile",
  "build_context_dir": "."
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique ID of the created service.
- **slug** (string) - The slug of the service.
- **type** (string) - The type of the service.
- **repository_url** (string) - The repository URL.
- **branch_name** (string) - The branch name.
- **builder** (string) - The builder used.
- **unapplied_changes** (array) - A list of unapplied changes to the service configuration.

#### Response Example
```json
{
  "id": "srv_git456xyz",
  "slug": "frontend",
  "type": "GIT_REPOSITORY",
  "repository_url": null,
  "branch_name": null,
  "builder": null,
  "unapplied_changes": [
    {
      "field": "git_source",
      "new_value": {
        "repository_url": "https://github.com/myorg/frontend.git",
        "branch_name": "main"
      }
    },
    {
      "field": "builder",
      "new_value": {
        "builder": "DOCKERFILE",
        "options": {"dockerfile_path": "./Dockerfile"}
      }
    }
  ]
}
```
```
Tokens:
Raw