# magnetikonline/docker-acestream-server architecture

> Architecture diagram of the GitHub repository magnetikonline/docker-acestream-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/magnetikonline/docker-acestream-server
- Repository: https://github.com/magnetikonline/docker-acestream-server

## Overview

This repository is a small Docker-based distribution of an Ace Stream server plus a thin client-side launcher.

1. **Core purpose**
   - The main artifact is a Docker image that runs the Ace Stream engine inside a Debian 8 slim container.
   - The image exposes the engine’s HTTP API on host port `6878`, so the host can both control streaming and consume the resulting media stream through one endpoint.

2. **Main runtime boundary**
   - The important boundary is **host OS ↔ Docker container ↔ Ace Stream engine**.
   - The container encapsulates the proprietary Ace Stream server process and its runtime dependencies.
   - External players such as VLC run on the host and connect back to the stream URL produced by the engine.

3. **Container build subsystem**
   - `Dockerfile` defines the image contents and runtime environment.
   - `build.sh` is the local entrypoint for building the image from source.
   - `version` is used as the version source for the packaged Ace Stream release/tagging.

4. **Container lifecycle / startup subsystem**
   - `run.sh` starts the container in the default configuration.
   - `run-tmpfs.sh` is an alternate startup path for Linux hosts that mounts the engine cache on `tmpfs` instead of disk.
   - This matters architecturally because the engine writes stream/cache data continuously, and the repo explicitly offers a RAM-backed cache option to reduce disk thrash.

5. **Stream control client**
   - `playstream.py` is the host-side orchestration script.
   - It sends an HTTP request to the Ace Stream server to start streaming a given program/content ID, then optionally launches a local media player once the stream is ready.
   - This script is the main integration point between the HTTP API and the user’s playback application.

6. **Data flow for playback**
   - User supplies an Ace Stream PID/hash to `playstream.py`.
   - `playstream.py` talks to the server at `127.0.0.1:6878` by default.
   - The engine starts the stream, negotiates peers, and exposes a local playback URL.
   - When ready, the script can hand that URL to a player like VLC.

7. **Operational feedback loop**
   - `playstream.py` can poll and print stream progress every 2 seconds.
   - The reported peer count and transfer rates are the key runtime signals for stream readiness and health.
   - This script is therefore not just a launcher; it is also the status/telemetry bridge for the user.

8. **Exposed service interface**
   - The primary service interface is the Ace Stream HTTP API on port `6878`.
   - The README shows a version check endpoint under `/webui/api/service?method=get_version`.
   - Architecturally, this is the only stable control plane required by the host scripts.

9. **Build and publish automation**
   - `hooks/build` and `hooks/push` indicate Docker Hub-style automated build and publish hooks.
   - These scripts likely support CI/CD for building the image and pushing tagged versions, making the repository both a source tree and an image release pipeline.

10. **Distribution model**
   - The project can be consumed in two ways: build locally with `build.sh`, or pull a prebuilt image from Docker Hub.
   - That split is important: the repo is designed primarily as a container distribution rather than a traditional application codebase.

11. **Architecture summary**
   - In diagram form, the repository consists of:
     - a **Docker image layer** containing Ace Stream server,
     - a **container startup layer** with default and tmpfs-backed launch scripts,
     - a **host orchestration layer** in Python for stream initiation and player handoff,
     - and an **external playback layer** represented by VLC or another compatible media player.

Main entry points: [`playstream.py`](https://github.com/magnetikonline/docker-acestream-server/blob/main/playstream.py) (Playstream), [`build.sh`](https://github.com/magnetikonline/docker-acestream-server/blob/main/build.sh) (Build image), [`Dockerfile`](https://github.com/magnetikonline/docker-acestream-server/tree/main/Dockerfile) (Dockerfile), [`run.sh`](https://github.com/magnetikonline/docker-acestream-server/blob/main/run.sh) (Run default)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host OS"]
  node_playstream["Playstream<br/>host launcher<br/>[playstream.py]"]
  node_player["Media player<br/>external player"]
  node_user(("User<br/>operator"))
end

subgraph group_container["Docker image"]
  node_dockerfile["Dockerfile<br/>image build spec"]
  node_version["Version<br/>release tag"]
  node_buildsh["Build image<br/>local build script<br/>[build.sh]"]
  node_runsh["Run default<br/>startup script<br/>[run.sh]"]
  node_runtmpfs["Run tmpfs<br/>startup script<br/>[run-tmpfs.sh]"]
  node_ace_container[("Ace Stream<br/>container runtime")]
  node_ace_engine(("Engine API<br/>http service"))
  node_cache["Stream cache<br/>runtime data"]
end

subgraph group_release["Release flow"]
  node_hooks_build["Hook build<br/>publish hook"]
  node_hooks_push["Hook push<br/>publish hook"]
end

subgraph group_external["External service"]
  node_dockerhub[("Docker Hub<br/>image registry")]
end

node_buildsh -->|"builds"| node_dockerfile
node_dockerfile -->|"reads"| node_version
node_buildsh -->|"produces"| node_ace_container
node_runsh -->|"starts"| node_ace_container
node_runtmpfs -->|"starts"| node_ace_container
node_ace_container -->|"hosts"| node_ace_engine
node_ace_engine -->|"writes"| node_cache
node_playstream -->|"controls"| node_ace_engine
node_playstream -->|"launches"| node_player
node_user -->|"invokes"| node_playstream
node_playstream -->|"reports"| node_user
node_ace_engine -->|"serves"| node_player
node_hooks_build -->|"builds"| node_dockerhub
node_hooks_push -->|"publishes"| node_dockerhub
node_playstream -.->|"polls"| node_ace_engine

click node_dockerfile "https://github.com/magnetikonline/docker-acestream-server/tree/main/Dockerfile"
click node_version "https://github.com/magnetikonline/docker-acestream-server/tree/main/version"
click node_buildsh "https://github.com/magnetikonline/docker-acestream-server/blob/main/build.sh"
click node_runsh "https://github.com/magnetikonline/docker-acestream-server/blob/main/run.sh"
click node_runtmpfs "https://github.com/magnetikonline/docker-acestream-server/blob/main/run-tmpfs.sh"
click node_playstream "https://github.com/magnetikonline/docker-acestream-server/blob/main/playstream.py"
click node_hooks_build "https://github.com/magnetikonline/docker-acestream-server/tree/main/hooks/build"
click node_hooks_push "https://github.com/magnetikonline/docker-acestream-server/tree/main/hooks/push"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_playstream,node_player,node_user toneBlue
class node_dockerfile,node_version,node_buildsh,node_runsh,node_runtmpfs,node_ace_container,node_ace_engine,node_cache toneAmber
class node_hooks_build,node_hooks_push toneMint
class node_dockerhub toneRose
```

## Components

### Host OS

Scripts and players that run on the machine outside Docker.

- [Playstream](https://github.com/magnetikonline/docker-acestream-server/blob/main/playstream.py): host launcher · Orchestrates stream start, monitors progress, and hands off playback to a media player. · `playstream.py`
- **Media player**: external player · Local playback client such as VLC that consumes the stream URL.
- **User**: operator · Supplies a PID/hash and chooses playback behavior.

### Docker image

Build and runtime boundary for the Ace Stream server.

- [Dockerfile](https://github.com/magnetikonline/docker-acestream-server/tree/main/Dockerfile): image build spec · Defines the Debian-based Ace Stream container image and runtime environment. · `Dockerfile`
- [Version](https://github.com/magnetikonline/docker-acestream-server/tree/main/version): release tag · Single source of the packaged Ace Stream version. · `version`
- [Build image](https://github.com/magnetikonline/docker-acestream-server/blob/main/build.sh): local build script · Builds the container image from the repository source. · `build.sh`
- [Run default](https://github.com/magnetikonline/docker-acestream-server/blob/main/run.sh): startup script · Starts the container with the standard disk-backed cache configuration. · `run.sh`
- [Run tmpfs](https://github.com/magnetikonline/docker-acestream-server/blob/main/run-tmpfs.sh): startup script · Starts the container with cache mounted on tmpfs for RAM-backed operation. · `run-tmpfs.sh`
- **Ace Stream**: container runtime · Dockerized Ace Stream engine and its bundled dependencies.
- **Engine API**: http service · Ace Stream server process exposing control and stream endpoints on port 6878.
- **Stream cache**: runtime data · Continuous stream and peer/cache writes used during playback.

### Release flow

Automation used to build and publish image artifacts.

- [Hook build](https://github.com/magnetikonline/docker-acestream-server/tree/main/hooks/build): publish hook · Automated Docker build hook for CI or registry workflows. · `hooks/build`
- [Hook push](https://github.com/magnetikonline/docker-acestream-server/tree/main/hooks/push): publish hook · Automated Docker push hook for publishing tagged images. · `hooks/push`

### External service

Runtime dependency outside the repository.

- **Docker Hub**: image registry · Prebuilt distribution target for the container image.

## Connections

- Build image → Dockerfile: builds · Uses the Dockerfile to create the image.
- Dockerfile → Version: reads · Pins the packaged Ace Stream release version.
- Build image → Ace Stream: produces · Creates the runnable container image.
- Run default → Ace Stream: starts · Launches the default container runtime.
- Run tmpfs → Ace Stream: starts · Launches the container with tmpfs-backed cache.
- Ace Stream → Engine API: hosts · Encapsulates the server process and dependencies.
- Engine API → Stream cache: writes · Stores stream and peer/cache data during playback.
- Playstream → Engine API: controls · Calls the HTTP API to start and query streams.
- Playstream → Media player: launches · Hands the ready stream URL to a local player.
- User → Playstream: invokes · Provides the content ID and runtime options.
- Playstream → User: reports · Prints stream progress, peers, and transfer rates.
- Engine API → Media player: serves · Exposes the local media stream consumed by the player.
- Hook build → Docker Hub: builds · Automates image creation in registry workflows.
- Hook push → Docker Hub: publishes · Automates image upload to the registry.
- Playstream → Engine API: polls · Checks readiness and status every few seconds.
