# 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