Docker Compose Remote Management API

This is a very simple API to manage Docker compose applications via HTTP requests and receive logs via WebSockets.

Installation

• Clone the repository
• Create a virtual environment using python -m venv venv (python 3.12+ is required)
• Activate the virtual environment using source venv/bin/activate
• Install the dependencies using pip install -r requirements.txt
• Create a config.json file in the projects root directory. See the config.json section for more information.
• Run the API using the start.sh script
  • It may be required to make the script executable using chmod +x start.sh
• The API should now run on port 9090

To set up a system-wide service, you can use the compose-remote-manager.service-unit-file-template.

Note

It's sadly not possible to dockerize this application, because it needs direct access to the host system to run the docker compose commands.

Usage

The API provides the following endpoints:

• GET /services - returns a list of all services that are accessible with a given access key
• GET /status/{service} - returns true if the service is running, false otherwise
• POST /start/{service} - runs docker compose up -d in the service directory (starts the service)
• POST /stop/{service} - runs docker compose down in the service directory (stops the service)
• GET /logs/{service} - returns the logs of the service (docker compose logs) format into an array of 3-tuples of the form (service, timestamp, log), where service is the name of the service as defined in the docker-compose.yml file.
• WS /ws/logs/{service} - establishes a WebSocket connection to the service and returns the logs as they are generated. Does not include old logs.
• POST /command/{service} - runs a custom command in the service directory. The command should be passed as a JSON object in the request body. For example: {"command": "ls -la"}. The response will be the output of the command.

The {service} parameter is the name of the service as defined in the config.json file.

To access services that require an access key, append the query parameter access_key to the request. For example: /logs/<service>?access_key=1234567890

Configuring the API

The config.json file contains the configuration for the docker compose applications and the access keys to access those applications. It should be in the following format:

{
    // These are variable keys that can be used to restrict access to certain services
    "access-keys": {
        "general": "1234567890"
        ...
    },
    // The services that should be accassible via the API
    "services": {
        // The name of the service
        "service-name": {
            // The path to the directory where the docker-compose.yml file is located
            "cwd": "/path/to/dir",
            // The access key that is required to access this service. If not specified, no access key is required
            "access-key": "$general" // <- This is a variable name
        },
        "another-service": {
            "cwd": "/path/to/dir",
            "access-key": "1234567890",
            // The name of the docker-compose file (default: docker-compose.yml)
            "compose-file": "docker-compose.prod.yml"
        },
        "third-service": {
            "cwd": "/path/to/dir",
              
            // It's also possible to use a list of access keys (logical OR)
            "access-key": [
                "abc",
                "def",
            ]
        },
        "forth-service": {
          "cwd": "/path/to/dir",

          // It's also possible to restrict an access key to certain scopes
          "access-key": {
            "key": "$general",  // Specify the key
            "scope": [          // Restrict to specific scopes
                "logs",
                "status"
            ] 
          }
        }
        ...
    }
}

For the access-key field you can either use a string or a variable name (prefixed with a $ sign) that is defined in the access-keys field. To use an access key, that starts with a $ sign, you have to escape it with a another $ sign. For example: $$general would require ...?access_key=$general.

An example config.json file can be found here.

Note on Docker compose services

Currently, it's not possible to start / stop / monitor single services defined in the docker-comopse.yml file. Only all services at once can be controlled.

See Also

The docker-compose-remote-manager-web-app build on top of this server docker compose services via a simple web GUI.