149 lines
4.0 KiB
Markdown
149 lines
4.0 KiB
Markdown
# 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](https://nodejs.org/) (v22 recommended)
|
|
- [Docker](https://www.docker.com/) running locally
|
|
- On Windows: Docker must be configured to expose the API on TCP (see below)
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository:
|
|
```sh
|
|
git clone https://git.netbyte.host/netbyte/bitstream.git
|
|
cd bitstream
|
|
```
|
|
2. Install dependencies:
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`
|
|
```json
|
|
{
|
|
"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:
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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
|