128 lines
3.3 KiB
Markdown
128 lines
3.3 KiB
Markdown
# Light Docker API
|
|
|
|
A Python/FastAPI REST API that provides a simplified, secure interface to Docker container operations. It runs as a Docker container itself and only manages containers it creates (tracked via labels).
|
|
|
|
## Features
|
|
|
|
- **Container Management**: Create, start, stop, restart, and remove containers
|
|
- **Container Isolation**: Only manages containers it creates (via labels)
|
|
- **Security Filters**: Blocks dangerous Docker options (privileged mode, host networking, etc.)
|
|
- **Resource Monitoring**: Get container logs and stats
|
|
- **Docker-like API**: Familiar endpoint structure for Docker users
|
|
|
|
## Quick Start
|
|
|
|
### Using Docker Compose
|
|
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
The API will be available at `http://localhost:8000`.
|
|
|
|
### Manual Docker Build
|
|
|
|
```bash
|
|
docker build -t light-docker-api .
|
|
docker run -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock:ro light-docker-api
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/` | API information |
|
|
| GET | `/health` | Health check |
|
|
| GET | `/containers` | List managed containers |
|
|
| POST | `/containers/create` | Create a new container |
|
|
| GET | `/containers/{id}` | Inspect a container |
|
|
| POST | `/containers/{id}/start` | Start a container |
|
|
| POST | `/containers/{id}/stop` | Stop a container |
|
|
| POST | `/containers/{id}/restart` | Restart a container |
|
|
| DELETE | `/containers/{id}` | Remove a container |
|
|
| GET | `/containers/{id}/logs` | Get container logs |
|
|
| GET | `/containers/{id}/stats` | Get container stats |
|
|
|
|
## Usage Examples
|
|
|
|
### Create a container
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/containers/create \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"image": "nginx", "name": "my-nginx"}'
|
|
```
|
|
|
|
### List containers
|
|
|
|
```bash
|
|
curl http://localhost:8000/containers
|
|
```
|
|
|
|
### Start a container
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/containers/{id}/start
|
|
```
|
|
|
|
### Get container logs
|
|
|
|
```bash
|
|
curl http://localhost:8000/containers/{id}/logs
|
|
```
|
|
|
|
### Remove a container
|
|
|
|
```bash
|
|
curl -X DELETE http://localhost:8000/containers/{id}
|
|
```
|
|
|
|
## Security Restrictions
|
|
|
|
The following options are blocked for security:
|
|
|
|
- `privileged: true` - Rejected
|
|
- `network_mode: host` - Rejected
|
|
- `pid_mode: host` - Rejected
|
|
- `ipc_mode: host` - Rejected
|
|
- `devices` - Rejected
|
|
- `cap_add` - Only allowed capabilities (none by default)
|
|
- Volume mounts to sensitive paths (`/`, `/etc`, `/var/run/docker.sock`, etc.)
|
|
|
|
## Configuration
|
|
|
|
Environment variables:
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `INSTANCE_ID` | Unique instance identifier | Random UUID |
|
|
| `LIGHT_DOCKER_API_CORS_ORIGINS` | CORS allowed origins | `["*"]` |
|
|
| `LIGHT_DOCKER_API_ALLOWED_IMAGES` | Allowed image list (empty = all) | `[]` |
|
|
|
|
## API Documentation
|
|
|
|
When running, interactive API documentation is available at:
|
|
|
|
- Swagger UI: `http://localhost:8000/docs`
|
|
- ReDoc: `http://localhost:8000/redoc`
|
|
|
|
## Container Tracking
|
|
|
|
Every container created through this API is labeled with:
|
|
|
|
- `light-docker-api.managed=true`
|
|
- `light-docker-api.instance={instance_id}`
|
|
|
|
Only containers with these labels are visible and manageable through the API.
|
|
|
|
## Development
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --reload
|
|
```
|
|
|
|
Note: Local development requires access to the Docker socket.
|