{"id":51229753,"url":"https://github.com/alilotfi23/dockmanager-api","last_synced_at":"2026-06-28T15:01:49.599Z","repository":{"id":367819757,"uuid":"1281187682","full_name":"alilotfi23/DockManager-API","owner":"alilotfi23","description":"A production-ready CRUD API for managing Docker resources","archived":false,"fork":false,"pushed_at":"2026-06-27T19:23:41.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-27T21:13:26.205Z","etag":null,"topics":["containers","docker","dockerfile","fastapi","jwt-authentication","linux","pagination","python3","rate-limit","role-based-access-control","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alilotfi23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-26T09:58:49.000Z","updated_at":"2026-06-27T19:23:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alilotfi23/DockManager-API","commit_stats":null,"previous_names":["alilotfi23/dockmanager-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/alilotfi23/DockManager-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FDockManager-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FDockManager-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FDockManager-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FDockManager-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alilotfi23","download_url":"https://codeload.github.com/alilotfi23/DockManager-API/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilotfi23%2FDockManager-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34892547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","docker","dockerfile","fastapi","jwt-authentication","linux","pagination","python3","rate-limit","role-based-access-control","sqlite3"],"created_at":"2026-06-28T15:01:43.695Z","updated_at":"2026-06-28T15:01:49.589Z","avatar_url":"https://github.com/alilotfi23.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Management API\n\nA production-ready CRUD API for managing Docker resources (containers, images, volumes, and networks) built with FastAPI. This API communicates directly with the Docker Engine REST API using raw HTTP requests via Unix socket, without using the Docker SDK.\n\n## Features\n\n- **Full Docker Resource Management**: CRUD operations for containers, images, volumes, and networks\n- **JWT Authentication**: Secure token-based authentication with access and refresh tokens\n- **Role-Based Access Control (RBAC)**: Admin (full access) and Viewer (read-only) roles\n- **Real-time Logs Streaming**: Both HTTP (SSE) and WebSocket endpoints for container logs\n- **Container Stats**: Live resource usage monitoring (CPU, memory, network I/O)\n- **System Endpoints**: Docker daemon info, version, disk usage, and global prune\n- **Pagination \u0026 Filtering**: All list endpoints support pagination and query filters\n- **Rate Limiting**: Protection against brute-force attacks on auth endpoints\n- **Structured Logging**: JSON logging with request IDs for tracing\n- **API Versioning**: Clean versioning structure (`/api/v1`) for future compatibility\n- **Docker Compose Ready**: Easy deployment with containerized setup\n\n## Technology Stack\n\n- **Python 3.11+**\n- **FastAPI**: Modern, fast web framework\n- **Pydantic v2**: Data validation and serialization\n- **httpx**: Async HTTP client for Docker Engine API communication\n- **SQLAlchemy 2.x (async)**: ORM with async support\n- **SQLite + aiosqlite**: Lightweight database\n- **Alembic**: Database migrations\n- **python-jose**: JWT token handling\n- **passlib[bcrypt]**: Password hashing\n- **slowapi**: Rate limiting\n- **structlog**: Structured logging\n\n## Project Structure\n\n```\n.\n├── app/\n│   ├── main.py                 # FastAPI application entry point\n│   ├── api/\n│   │   ├── deps.py             # API dependencies (auth, RBAC, pagination)\n│   │   └── v1/\n│   │       ├── api.py          # v1 API router aggregator\n│   │       └── routes/\n│   │           ├── auth.py      # Authentication endpoints\n│   │           ├── containers.py # Container management\n│   │           ├── images.py    # Image management\n│   │           ├── volumes.py   # Volume management\n│   │           ├── networks.py  # Network management\n│   │           └── system.py    # System endpoints\n│   ├── core/\n│   │   ├── config.py           # Application configuration\n│   │   └── security.py         # JWT and password hashing\n│   ├── db/\n│   │   ├── models.py           # SQLAlchemy models\n│   │   └── session.py          # Database session management\n│   ├── schemas/\n│   │   ├── auth.py             # Auth Pydantic schemas\n│   │   └── docker.py           # Docker resource schemas\n│   └── services/\n│       └── docker_client.py    # Docker Engine API client wrapper\n├── alembic/                    # Database migrations\n├── tests/                      # Pytest tests\n├── Dockerfile                  # Container image definition\n├── docker-compose.yml          # Docker Compose configuration\n├── requirements.txt            # Python dependencies\n├── .env.example                # Environment variables template\n├── Makefile                    # Convenience commands\n├── api.http                    # VS Code REST Client collection\n└── README.md                   # This file\n```\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11 or higher\n- Docker and Docker Compose (for containerized deployment)\n- Docker daemon running (for API functionality)\n\n### Local Development\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd python\n   ```\n\n2. **Create a virtual environment**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies**\n   ```bash\n   make install\n   # or\n   pip install -r requirements.txt\n   ```\n\n4. **Configure environment variables**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your settings\n   ```\n\n5. **Run the application**\n   ```bash\n   make dev\n   # or\n   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n   ```\n\nThe API will be available at `http://localhost:8000`\n\n### Docker Deployment\n\n1. **Build and start with Docker Compose**\n   ```bash\n   make up\n   # or\n   docker-compose up -d\n   ```\n\n2. **View logs**\n   ```bash\n   make logs\n   # or\n   docker-compose logs -f\n   ```\n\n3. **Stop the application**\n   ```bash\n   make down\n   # or\n   docker-compose down\n   ```\n\n## Configuration\n\nEnvironment variables are configured via `.env` file:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SECRET_KEY` | JWT signing key (change in production!) | `your-secret-key-change-this` |\n| `DATABASE_URL` | Database connection string | `sqlite+aiosqlite:///./app.db` |\n| `DOCKER_HOST` | Docker daemon socket path | `http+unix://%2Fvar%2Frun%2Fdocker.sock` |\n| `DOCKER_API_VERSION` | Docker Engine API version | `v1.45` |\n| `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000,http://localhost:8080` |\n| `ACCESS_TOKEN_EXPIRE_MINUTES` | Access token lifetime | `30` |\n| `REFRESH_TOKEN_EXPIRE_DAYS` | Refresh token lifetime | `7` |\n| `LOG_LEVEL` | Logging level | `INFO` |\n\n### Docker Host Configuration\n\nThe `DOCKER_HOST` variable depends on your platform:\n\n- **Linux/Mac**: `http+unix://%2Fvar%2Frun%2Fdocker.sock` (URL-encoded `/var/run/docker.sock`)\n- **Windows (named pipes)**: `npipe://./pipe/docker_engine`\n- **TCP**: `http://localhost:2375` (if daemon configured for TCP)\n\n## API Documentation\n\nOnce the application is running, visit:\n\n- **Swagger UI**: `http://localhost:8000/docs`\n- **ReDoc**: `http://localhost:8000/redoc`\n\n## API Endpoints\n\n### Authentication\n\nAll Docker management endpoints require authentication. Use the auth endpoints to obtain tokens.\n\n#### Register User\n```bash\nPOST /api/v1/auth/register\nContent-Type: application/json\n\n{\n  \"username\": \"testuser\",\n  \"email\": \"test@example.com\",\n  \"password\": \"password123\",\n  \"role\": \"viewer\"  // or \"admin\"\n}\n```\n\n#### Login\n```bash\nPOST /api/v1/auth/login\nContent-Type: application/x-www-form-urlencoded\n\nusername=testuser\u0026password=password123\n```\n\nResponse:\n```json\n{\n  \"access_token\": \"eyJ...\",\n  \"refresh_token\": \"eyJ...\",\n  \"token_type\": \"bearer\"\n}\n```\n\n#### Refresh Token\n```bash\nPOST /api/v1/auth/refresh\nContent-Type: application/json\n\n{\n  \"refresh_token\": \"your_refresh_token\"\n}\n```\n\n### Containers\n\n#### List Containers\n```bash\nGET /api/v1/containers?all=true\u0026limit=10\u0026offset=0\u0026status=running\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Create Container\n```bash\nPOST /api/v1/containers\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"name\": \"my-nginx\",\n  \"image\": \"nginx:latest\",\n  \"ports\": {\"80/tcp\": \"8080\"},\n  \"restart_policy\": \"unless-stopped\"\n}\n```\n\n#### Start/Stop/Restart Container\n```bash\nPOST /api/v1/containers/{id}/start\nPOST /api/v1/containers/{id}/stop\nPOST /api/v1/containers/{id}/restart\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Remove Container\n```bash\nDELETE /api/v1/containers/{id}?force=true\u0026remove_volumes=true\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Execute Command in Container\n```bash\nPOST /api/v1/containers/{id}/exec\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"command\": [\"ls\", \"-la\"],\n  \"working_dir\": \"/app\"\n}\n```\n\n#### Get Container Logs\n```bash\n# Non-streaming\nGET /api/v1/containers/{id}/logs?tail=100\u0026since=1640995200\nAuthorization: Bearer \u003caccess_token\u003e\n\n# Streaming (SSE)\nGET /api/v1/containers/{id}/logs/stream?tail=50\nAuthorization: Bearer \u003caccess_token\u003e\n\n# WebSocket\nWS /api/v1/containers/{id}/logs/ws\n```\n\n#### Get Container Stats\n```bash\n# Single snapshot\nGET /api/v1/containers/{id}/stats\nAuthorization: Bearer \u003caccess_token\u003e\n\n# Streaming (SSE)\nGET /api/v1/containers/{id}/stats?stream=true\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Prune Stopped Containers\n```bash\nPOST /api/v1/containers/prune\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### Images\n\n#### List Images\n```bash\nGET /api/v1/images?all=true\u0026name=nginx\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Pull Image\n```bash\nPOST /api/v1/images/pull\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"from_image\": \"nginx\",\n  \"tag\": \"latest\",\n  \"platform\": \"linux/amd64\"\n}\n```\n\n#### Tag Image\n```bash\nPOST /api/v1/images/tag\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"source\": \"nginx:latest\",\n  \"target\": \"my-registry/nginx:v1.0\"\n}\n```\n\n#### Remove Image\n```bash\nDELETE /api/v1/images/{id}?force=true\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Prune Images\n```bash\nPOST /api/v1/images/prune?dangling=false\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### Volumes\n\n#### List Volumes\n```bash\nGET /api/v1/volumes\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Create Volume\n```bash\nPOST /api/v1/volumes\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"name\": \"my-volume\",\n  \"driver\": \"local\",\n  \"labels\": {\"env\": \"production\"}\n}\n```\n\n#### Remove Volume\n```bash\nDELETE /api/v1/volumes/{name}?force=true\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Prune Volumes\n```bash\nPOST /api/v1/volumes/prune\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### Networks\n\n#### List Networks\n```bash\nGET /api/v1/networks?name=my-network\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Create Network\n```bash\nPOST /api/v1/networks\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"name\": \"my-network\",\n  \"driver\": \"bridge\",\n  \"subnet\": \"172.20.0.0/16\",\n  \"gateway\": \"172.20.0.1\"\n}\n```\n\n#### Connect Container to Network\n```bash\nPOST /api/v1/networks/{id}/connect\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"container\": \"container_name_or_id\"\n}\n```\n\n#### Disconnect Container from Network\n```bash\nPOST /api/v1/networks/{id}/disconnect\nAuthorization: Bearer \u003caccess_token\u003e\nContent-Type: application/json\n\n{\n  \"container\": \"container_name_or_id\",\n  \"force\": false\n}\n```\n\n#### Prune Networks\n```bash\nPOST /api/v1/networks/prune\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### System\n\n#### Get Docker Info\n```bash\nGET /api/v1/system/info\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Get Docker Version\n```bash\nGET /api/v1/system/version\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Get Disk Usage\n```bash\nGET /api/v1/system/df\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n#### Prune All Resources\n```bash\nPOST /api/v1/system/prune\nAuthorization: Bearer \u003caccess_token\u003e\n```\n\n### Health Check\n\n```bash\nGET /health\n```\n\nReturns API health and Docker daemon connectivity status.\n\n## Role-Based Access Control\n\n- **Admin Role**: Full access to all endpoints (CRUD operations)\n- **Viewer Role**: Read-only access to GET endpoints only\n\nAll write operations (POST, PUT, DELETE) require admin role.\n\n## Makefile Commands\n\n```bash\nmake help          # Show all available commands\nmake install       # Install Python dependencies\nmake up            # Start with docker-compose\nmake down          # Stop with docker-compose\nmake restart       # Restart the application\nmake logs          # View application logs\nmake dev           # Run in development mode\nmake test          # Run tests\nmake test-coverage # Run tests with coverage\nmake migrate       # Run database migrations\nmake migrate-create MSG=\"description\"  # Create new migration\nmake migrate-downgrade  # Rollback last migration\nmake lint          # Run linting\nmake format        # Format code\nmake clean         # Clean generated files\nmake build         # Build Docker image\nmake rebuild       # Rebuild without cache\nmake shell         # Open shell in container\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\nmake test\n```\n\nRun tests with coverage:\n\n```bash\nmake test-coverage\n```\n\nTests use pytest with mocked Docker API calls to avoid requiring a running Docker daemon during testing.\n\n## Database Migrations\n\n### Create a new migration\n```bash\nmake migrate-create MSG=\"add_new_field\"\n```\n\n### Run migrations\n```bash\nmake migrate\n```\n\n### Rollback last migration\n```bash\nmake migrate-downgrade\n```\n\n## API Client Collection\n\nThe `api.http` file contains a comprehensive collection of HTTP requests for all endpoints. Use it with the VS Code REST Client extension or similar tools.\n\n## Security Considerations\n\n1. **Change the SECRET_KEY**: Never use the default secret key in production\n2. **Use HTTPS**: Deploy behind a reverse proxy with SSL/TLS\n3. **Docker Socket Access**: The container needs access to the Docker socket - ensure proper permissions\n4. **Rate Limiting**: Auth endpoints are rate-limited to prevent brute-force attacks\n5. **RBAC**: Use role-based access control to limit write operations\n6. **CORS**: Configure allowed origins appropriately for your environment\n\n## Troubleshooting\n\n### Docker Daemon Unreachable\n\nIf the API returns 503 on health check:\n\n1. Verify Docker daemon is running: `docker ps`\n2. Check `DOCKER_HOST` configuration in `.env`\n3. Ensure the Docker socket is mounted correctly in docker-compose.yml\n4. Check permissions on `/var/run/docker.sock`\n\n### Database Issues\n\nIf you encounter database errors:\n\n1. Run migrations: `make migrate`\n2. Check database file permissions\n3. Verify `DATABASE_URL` in `.env`\n\n### Container Creation Fails\n\nIf container creation fails:\n\n1. Verify the image exists locally or can be pulled\n2. Check port conflicts\n3. Review container configuration (ports, volumes, etc.)\n4. Check Docker daemon logs: `docker logs docker-api`\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run tests: `make test`\n6. Submit a pull request\n\n## License\n\nThis project is provided as-is for educational and production use.\n\n## Support\n\nFor issues and questions, please open an issue on the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falilotfi23%2Fdockmanager-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falilotfi23%2Fdockmanager-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falilotfi23%2Fdockmanager-api/lists"}