README
¶
DockerAPI
DockerAPI is a lightweight HTTP API for managing Docker containers and images, with optional support for Docker Compose profiles.
Features
- Container operations: restart, stop, start, remove
- Image operations: pull
- Docker Compose operations: pull, up, down, restart, stop, start
- Authentication via bearer token
- Configurable permissions for different operations
- JSON and pretty-printed output formats
- Logging with configurable levels
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" -d '
{
"operation": "pull",
"service": "nginx",
"profile": "nginx"
}
' http://localhost:9999/compose
{"message":"Operation pull completed successfully on service nginx"}
Requirements
- Go 1.22 or later
- Docker
- Optional: Docker Compose (for Compose operations)
Installation
go install
go install github.com/sammcj/dockerAPI@HEAD
From Binary
-
Download the latest release from the Releases page.
-
Extract the tarball:
tar -xvf dockerapi_*.tar.gz cd dockerapi
-
Run the application:
./dockerapi [flags]
From Source
-
Clone the repository:
git clone https://github.com/sammcj/dockerAPI.git cd dockerAPI
-
Build the application:
make build
Usage
Running the API
./dockerapi [flags]
Flags
--auth-token
: Auth token for API requests--allow-restart
: Allow container restart operation (default true)--allow-stop
: Allow container stop operation (default true)--allow-start
: Allow container start operation (default true)--allow-remove
: Allow container remove operation (default false)--allow-pull
: Allow image pull operation (default true)--allow-compose
: Allow Docker Compose operations (default true)--port
: Port to listen on (default 8080)--log-level
: Log level (debug, info, warn, error) (default "info")--compose-path
: Path to Docker Compose project (default "./")-v
: Print the version and exit--help-api
: Show usage examples
API Endpoints
/container
: Container operations/image
: Image operations/compose
: Docker Compose operations
For detailed API usage examples, run ./dockerapi --help-api
.
Example API Requests
For pretty-printed output, add ?format=pretty to the URL of any request, e.g. http://localhost:8080/container?format=pretty
Restart a container:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "restart",
"container": "my-container"
}
' \
http://localhost:8080/container
Stop a container:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "stop",
"container": "my-container"
}
' \
http://localhost:8080/container
Start a container:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "start",
"container": "my-container"
}
' \
http://localhost:8080/container
Remove a stopped container:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "remove",
"container": "my-container"
}
' \
http://localhost:8080/container
Pull an image:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "pull",
"image": "nginx:latest"
}
' \
http://localhost:8080/image
Docker Compose - Restart a service:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "restart",
"service": "web",
"profile": "development"
}
' \
http://localhost:8080/compose
Docker Compose - Stop a service:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "stop",
"service": "web",
"profile": "development"
}
' \
http://localhost:8080/compose
Docker Compose - Start a service:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "start",
"service": "web",
"profile": "development"
}
' \
http://localhost:8080/compose
Docker Compose - Remove a service:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "remove",
"service": "web",
"profile": "development"
}
' \
http://localhost:8080/compose
Docker Compose - Pull images for a service:
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" \
-d '
{
"operation": "pull",
"service": "web",
"profile": "development"
}
' \
http://localhost:8080/compose
For pretty-printed output, add ?format=pretty to the URL, e.g. http://localhost:8080/compose?format=pretty
Docker Deployment
A Dockerfile and docker-compose.yml are provided for easy deployment. To run DockerAPI in a container:
-
Build the Docker image:
docker build -t dockerapi .
-
Run the container:
docker run -d -p 8080:8080 -v /var/run/docker.sock:/var/run/docker.sock dockerapi
Alternatively, use Docker Compose (after editing the docker-compose.yml file):
docker-compose up -d
Security Considerations
- Use HTTPS in production to secure API communications.
- Limit access to the Docker socket and DockerAPI.
- You can use a docker socket proxy such as Tecnativa/docker-socket-proxy to restrict access to the Docker socket and expose a secure API to DockerAPI.
- Regularly update dependencies and the base image.
- Use the principle of least privilege when configuring allowed operations.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
- Copyright 2024 Sam McLeod
- This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
There is no documentation for this package.