Bitstream (Docker Management Server)

This project provides a Node.js backend server for managing Docker containers and images, with real-time stats via WebSocket. It is built using Express, Dockerode, and supports CORS for frontend integration.

Features

• List all Docker containers (running and stopped)
• Start, stop, restart, and delete containers
• Create and run new containers with custom options
• View container stats (CPU, memory, network, block I/O)
• View container logs
• List available Docker images
• Pull new images from Docker Hub
• Get Docker system info
• Real-time container stats updates via WebSocket

API Endpoints

Containers

• GET /api/containers — List all containers
• GET /api/containers/:id/stats — Get stats for a container
• POST /api/containers/:id/start — Start a container
• POST /api/containers/:id/stop — Stop a container
• POST /api/containers/:id/restart — Restart a container
• POST /api/containers/create — Create and start a new container
• DELETE /api/containers/:id — Delete a container
• GET /api/containers/:id/logs — Get logs for a container

Images

• GET /api/images — List Docker images
• POST /api/images/pull — Pull a Docker image (body: { image: "<image-name>" })

System

• GET /api/system/info — Get Docker system info

WebSocket

• Connect to the server via WebSocket (same port) to receive real-time container stats updates.

Getting Started

Prerequisites

• Node.js (v22 recommended)
• Docker running locally
• On Windows: Docker must be configured to expose the API on TCP (see below)

Installation

1. Clone the repository:

   git clone https://git.netbyte.host/netbyte/bitstream.git
   cd bitstream
   

2. Install dependencies:

   yarn
   # or
   npm install
   

Configuration

• Linux/Mac: Uses Docker socket at /var/run/docker.sock by default.
• Windows:
  • Edit server.js and set Docker connection to { host: '127.0.0.1', port: 2375 }.
  • Ensure Docker is configured to expose the API on TCP port 2375 (insecure).

Running the Server

node server.js

The server will start on port 3001 by default (or set PORT environment variable).

API Authentication (Secret Key)

Bitstream requires a secret API key for all requests. This prevents unauthorized access (like Pterodactyl's Wings).

Generating a Key

Run the following command to generate a new API secret:

npm run keygen

Copy the printed key and store it in a .env file at the root of your project:

BITSTREAM_API_SECRET=your-generated-key-here

You can use .env.example as a template.

All API requests must include the header:

x-api-key: your-generated-key-here

If the key is missing or incorrect, the server will return 401 Unauthorized.

Example: Creating a Container

POST /api/containers/create

{
  "name": "my-nginx",
  "image": "nginx:latest",
  "ports": { "80/tcp": [{ "HostPort": "8080" }] },
  "environment": ["ENV_VAR=value"],
  "volumes": ["/host/path:/container/path"]
}

Real-Time Stats

Connect to the WebSocket endpoint (same port) to receive periodic stats updates for all running containers.

Running as a systemd Service

A sample systemd unit file is provided in systemd/bitstream.service. To use:

1. Copy the file to /etc/systemd/system/bitstream.service (edit paths as needed).
2. Set WorkingDirectory and EnvironmentFile to your Bitstream install location.
3. Create a dedicated user (e.g., bitstream) for security. (optional)
4. Reload systemd and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable --now bitstream
   sudo systemctl status bitstream
   

Debug Mode

You can run Bitstream in debug mode to log all API requests and see more detailed output:

node server.js --debug
# or
yarn dev --debug

When debug mode is enabled, all API interactions (method, path, status, duration) are logged to the console.

License

MIT