This API can be used to manage apps running as Docker containers on a server. Functionality includes creating, running, and killing apps, as well as getting an app's status, resource usage, and uptime logs. This API also supports Docker in swarm mode, which runs on a cluster of servers that shares tasks with automatic load balancing. This API was created for demo purposes, so it is not intended to run on systems where security is paramount.

This is a comprehensive guide of the entire API but a quick plaintext outline of all endpoints can be found at the base url.

1. General Notes
2. Setup Guide
3. API Endpoints (usage and examples)

When an app is created, the image and user name are provided, then the Docker container is made with the name "[IMAGE_NAME]--[USER_NAME]". All subsequent references to this container will use this name.

Usernames and image names can include uppercase and lowercase letters and numbers, as well as dashes, underscores. However, usernames cannot have double dashes, nor can they start with a dash because a double dash is used to deliminate the username from the image name in the container naming convention. Image names in docker hub are already unique, but user names must be unique as well.

Each server will be identified by a unique key in order to specify which one to interface with. For demo purposes, this API only responds to a placeholder server with the ID "demo", however in production this is how you would specify your seperate servers.

This API has methods for working with a standard docker setup as well as as docker's swarm mode. Swarm mode is a way to load balance apps across a cluster of servers, where one manager node delegates tasks amongst itself and its worker nodes. You can read more about Docker swarm mode here. Solo mode is the term used for docker's standard functionality, with just one node hosting containers. Because swarm mode uses services instead of standard containers, there are many key differences between these two modes:

Note: The word "container" is generally associated with solo mode, and the word "service" is generally associated with swarm mode, however both are interchangeable with the word "app"

Most GET methods this API provides return data from a corresponding docker command. If you want more information about a method or what it returns, check out the docker documentation about that command for a more direct explanation.

• CentOS 7
• Internet connection
• All nodes must have unique hostnames (swarm mode)

Run this command (you may be asked for sudo password):

bash <(curl -s https://raw.githubusercontent.com/JaxsonP/docker-dash/master/server/scripts/solo_install.sh)

This will download all files and install and configure Docker and Python 3.9.16. This can take up to 5-10 minutes. You will be prompted to restart, then run the start-server script to start the API. If you are in the docker-dash/ folder the command will be:

./start-server

Run this command (you may be asked for sudo password):

bash <(curl -s https://raw.githubusercontent.com/JaxsonP/docker-dash/master/server/scripts/swarm_install.sh)

This will download all files and install and configure Docker and Python 3.9.16. This can take up to 5-10 minutes. You will be prompted to restart, and you can start setting up the worker nodes. The specific command to use will be saved in a file called join_command.txt, but it should look something like:

bash <(curl -s https://raw.githubusercontent.com/JaxsonP/docker-dash/master/server/scripts/swarm_install_worker.sh) [SWARM_TOKEN] [MANAGER_IP_ADDRESS]:2377

Run this command on each worker node to complete setup. This script will first add the node to the swarm as a manager so that it can configure itself, then it will demote itself to worker. Once that is done, you can navigate to the docker-dash/ directory on the true manager node and start the server with:

./start-server

Note: In order to run main.py, you must either explicitly use venv/bin/python (like shown) or manually activate the virtual environment with source venv/bin/activate.

1. Start App
2. Stop App
3. Pause App
4. Unpause App
5. Restart App
6. Kill App
7. Create App
8. Delete App
9. Hard Reset App
10. Get Users
11. Get App Names
12. Get App Status
13. Get App Stats
14. Get App Info
15. Get Node Names
16. Get Node Status
17. Get Node Info
18. Get App Uptime Summary
19. Request Image
20. Get Images

<POST> http:https://placeholder.url/[SERVER_ID]/start-app?name=[APP_NAME]

This method is compatible with solo mode only.

Starts the specified app using the docker start command. Trying to start an app that is paused will return an error, a paused app must be unpaused.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to start, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/stop-app?name=[APP_NAME]

This method is compatible with solo mode only.

Signals for the specified app to exit using the docker stop command. If the container does not respond to the SIGTERM signal within a 10 second grace period, it will kill the container forcefully with SIGKILL.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to stop, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/pause-app?name=[APP_NAME]

This method is compatible with solo mode only.

Pauses the specified app using the docker pause command. An app must be already running in order to be paused, otherwise the api will return error. While an app is paused, it can be unpaused, stopped, restarted, or killed.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to pause, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/unpause-app?name=[APP_NAME]

This method is compatible with solo mode only.

Unpauses the specified app using the docker unpause command. An app must be paused, otherwise the api will return error.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to unpause, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/restart-app?name=[APP_NAME]

This method is compatible with solo mode only.

Restarts the specified app using the docker restart command. This command behaves similarly to a docker stop then a docker start command.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to restart, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/kill-app?name=[APP_NAME]

This method is compatible with both solo and swarm mode.

Kills the specified app by forcefully stopping the container with a SIGKILL signal. Not as graceful as the Stop App method, and therefore not recommended.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to kill, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/create-app?image=[IMAGE_NAME]&user=[USER_NAME]

This method is compatible with both solo and swarm mode.

Creates an app instance using the image specified. Once created, the container will be called 'IMAGE_NAME--USER_NAME'. The image must have already been requested and approved in order to be used to create an app.

SERVER_ID - Server-specific identifier

IMAGE_NAME - Name of the image to load the app from

USER_NAME - Name of the user who is using the app

<POST> http:https://placeholder.url/[SERVER_ID]/delete-app?name=[APP_NAME]

This method is compatible with solo mode only.

Deletes the specified app, removing ALL related data.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to delete, following the naming conventions.

<POST> http:https://placeholder.url/[SERVER_ID]/hard-reset-app?name=[APP_NAME]

This method is compatible with solo mode only.

Resets the specified app, clearing ALL data and restoring it from the original image. Under the hood this method stops and deletes the app instance, then recreates it from the source image.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to reset, following the naming conventions.

<GET> http:https://placeholder.url/[SERVER_ID]/get-users

This method is compatible with both solo and swarm mode.

Returns an array of all users that have apps (either running or stopped) on the specified server

SERVER_ID - Server-specific identifier

["john", "admin", "sarah"]

<GET> http:https://placeholder.url/[SERVER_ID]/get-app-names?user=[USER]

This method is compatible with both solo and swarm mode.

Returns an array of all existing apps on the specified server, regardless of its state (e.g. running, exited). If the USER parameter is not omitted, only the apps belonging to the given user will be returned

SERVER_ID - Server-specific identifier

USER (optional) : Name of user to query for

["jupyter-lab--john", "xterm--admin", "httpd--sarah"]

<GET> http:https://placeholder.url/[SERVER_ID]/get-app-status?name=[APP_NAME]

This method is compatible with both solo and swarm mode.

Returns basic information and status, in json format. This method returns the output of the docker ps commmand. Returns app resource information in json format, using the docker stats commmand. In swarm mode, it uses ssh to get info from the required node, so it may break if there are problems with the network or ssh configuration.

SERVER_ID - Server-specific identifier

APP_NAME (optional) : Name of app to query, following the naming conventions. If omitted, will return a list of all apps and statuses.

{
  "Command": "\"/docker-entrypoint.…\"",
  "CreatedAt": "2021-03-10 00:15:05 +0100 CET",
  "ID": "a762a2b37a1d",
  "Image": "jupyter-lab",
  "Labels": "",
  "LocalVolumes": "0",
  "Mounts": "",
  "Names": "jupyter-lab",
  "Networks": "bridge",
  "Ports": "80/tcp",
  "RunningFor": "4 seconds ago",
  "Size": "0B",
  "State": "running",
  "Status": "Up 3 seconds"
}

<GET> http:https://placeholder.url/[SERVER_ID]/get-app-stats?name=[APP_NAME]

This method is compatible with both solo and swarm mode.

Returns app resource information in json format, using the docker stats commmand. In swarm mode, this method uses ssh to get info from the required node, so it may break if there are problems with the network or ssh configuration.

SERVER_ID - Server-specific identifier

APP_NAME (optional) : Name of app to query, following the naming conventions. If omitted, will return a list of all apps' information.

{
  "BlockIO": "0B / 0B",
  "CPUPerc": "0.02%",
  "Container": "0203b8e9c65b",
  "ID": "0203b8e9c65b",
  "MemPerc": "0.38%",
  "MemUsage": "29.92MiB / 7.668GiB",
  "Name": "testcontainer",
  "NetIO": "1.01kB / 0B",
  "PIDs": "82"
}

<GET> http:https://placeholder.url/[SERVER_ID]/get-app-info?name=[APP_NAME]

This method is compatible with both solo and swarm mode.

Returns detailed information of specified app, in json format. This method uses the docker inspect commmand, it will return identical data.

SERVER_ID - Server-specific identifier

APP_NAME - Name of app to query, following the naming conventions.

{
  "Id": "d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47",
  "Created": "2015-06-08T16:18:02.505155285Z",
  "Path": "bash",
  "Args": [],
  "State": {
    "Running": false,
    "Paused": false,
    "Restarting": false,
    "OOMKilled": false,
    "Dead": false,
    "Pid": 0,
    "ExitCode": 0,
    "Error": "",
    "StartedAt": "2015-06-08T16:18:03.643865954Z",
    "FinishedAt": "2015-06-08T16:57:06.448552862Z"
  },
  "Image": "ded7cd95e059788f2586a51c275a4f151653779d6a7f4dad77c2bd34601d94e4",
  "NetworkSettings": {
    "Bridge": "",
    "SandboxID": "6b4851d1903e16dd6a567bd526553a86664361f31036eaaa2f8454d6f4611f6f",
    "HairpinMode": false,
    "LinkLocalIPv6Address": "",
    "LinkLocalIPv6PrefixLen": 0,
    "Ports": {},
    "SandboxKey": "/var/run/docker/netns/6b4851d1903e",
    "SecondaryIPAddresses": null,
    "SecondaryIPv6Addresses": null,
... continues for >100 lines ...

<GET> http:https://placeholder.url/[SERVER_ID]/get-node-names

This method is compatible with both solo and swarm mode.

Returns an array of the hostnames of all nodes in the swarm, or if the node is running in solo mode, it will return a list who's only element is its own hostname.

SERVER_ID - Server-specific identifier

["localhost.server1", "localhost.server2", "localhost.server3"]

<GET> http:https://placeholder.url/[SERVER_ID]/get-node-status?hostname=[HOSTNAME]

This method is compatible with both solo and swarm mode.

Returns basic status info about nodes in a swarm network, in json format. Under the hood, this method returns the output of docker node ls. If the node is not in swarm mode, it will still return it's own status info in an array with length 1, albiet some fields are unobtainable in solo mode and will be omitted.

SERVER_ID - Server-specific identifier

HOSTNAME (optional) - Hostname of the node to query. If omitted, will return a list of all nodes and their statuses.

{
   "Availability":"Active",
   "Hostname":"localhost.server2",
   "ManagerStatus":"Leader",
   "Self":false,
   "Status":"Ready",
}

<GET> http:https://placeholder.url/[SERVER_ID]/get-node-info?hostname=[HOSTNAME]

This method is compatible with swarm mode only.

Returns detailed information of a specific node in the swarm network, in json format. Under the hood, this method uses the docker node inspect commmand, it will return identical data.

SERVER_ID - Server-specific identifier

HOSTNAME - Hostname of the node to query

[
  {
    "ID": "dnv2tbnt2kcpgw90o3dvo99x2",
    "Version": {
      "Index": 361
    },
    "CreatedAt": "2023-06-27T20:26:14.950110744Z",
    "UpdatedAt": "2023-06-30T18:38:13.305299037Z",
    "Spec": {
      "Labels": {
        
      },
      "Role": "worker",
      "Availability": "active"
    },
    "Description": {
      "Hostname": "localhost.server2",
      "Platform": {
        "Architecture": "x86_64",
        "OS": "linux"
      },
      "Resources": {
        "NanoCPUs": 1000000000,
        "MemoryBytes": 1927254016
      },
      "Engine": {
        "EngineVersion": "24.0.2",
        "Plugins": [
          {
            "Type": "Log",
            "Name": "awslogs"
          },
          {
            "Type": "Log",
            "Name": "fluentd"
          },
... continues for >70 lines ...

<GET> http:https://placeholder.url/[SERVER_ID]/get-uptime-summary?name=[APP_NAME]&duration=[DURATION]

This method is compatible with both solo and swarm mode.

Returns timestamped log data representing uptime since the duration specified in the parameter. Possible durations are "hour", "day", "week", or "month". Output is true if the app status is 'running', and false if it is anything else.

SERVER_ID - Server-specific identifier

APP_NAME - Server-specific identifier

DURATION - String to specify duration of log data to return. (must be "hour", "day", "week", or "month")

{
  "2023-06-20T13:50:45": true,
  "2023-06-20T13:56:44": true,
  "2023-06-20T14:03:16": true,
  "2023-06-20T14:13:17": true,
  "2023-06-20T14:23:17": true,
  "2023-06-20T14:33:17": false,
  "2023-06-20T14:43:18": false
}

<POST> http:https://placeholder.url/[SERVER_ID]/request-image?image=[IMAGE_NAME]

This method is compatible with both solo and swarm mode.

Request an image to be pulled from docker hub.

SERVER_ID - Server-specific identifier

IMAGE_NAME - Name of requested image

<GET> http:https://placeholder.url/[SERVER_ID]/get-images

This method is compatible with both solo and swarm mode.

Returns an array of all existing images on the specified server. On top of the image information given by docker, another field called CreatedContainerCount will give the number of existing containers that were created from that image.

SERVER_ID - Server-specific identifier

[
  {
    "Containers": "N/A",
    "CreatedAt": "2023-06-14 10:45:43 -1000 HST",
    "CreatedSince": "7 days ago",
    "Digest": "<none>",
    "ID": "ad303d7f80f9",
    "Repository": "httpd",
    "SharedSize": "N/A",
    "Size": "168MB",
    "Tag": "latest",
    "UniqueSize": "N/A",
    "VirtualSize": "168.1MB",
    "CreatedContainerCount": 2
  },
  {
    "Containers": "N/A",
    "CreatedAt": "2023-06-13 07:45:16 -1000 HST",
    "CreatedSince": "8 days ago",
    "Digest": "<none>",
    "ID": "09b1cac8826b",
    "Repository": "python",
    "SharedSize": "N/A",
    "Size": "1.01GB",
    "Tag": "latest",
    "UniqueSize": "N/A",
    "VirtualSize": "1.008GB",
    "CreatedContainerCount": 1
  }
]