How magnetikonline/docker-acestream-server works
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 Playstream · build.sh Build image · Dockerfile Dockerfile · run.sh Run default
Components 14
Host OS
Scripts and players that run on the machine outside Docker.
- Playstream · Orchestrates stream start, monitors progress, and hands off playback to a media player.
playstream.py - Media player · Local playback client such as VLC that consumes the stream URL.
- User · Supplies a PID/hash and chooses playback behavior.
Docker image
Build and runtime boundary for the Ace Stream server.
- Dockerfile · Defines the Debian-based Ace Stream container image and runtime environment.
Dockerfile - Version · Single source of the packaged Ace Stream version.
version - Build image · Builds the container image from the repository source.
build.sh - Run default · Starts the container with the standard disk-backed cache configuration.
run.sh - Run tmpfs · Starts the container with cache mounted on tmpfs for RAM-backed operation.
run-tmpfs.sh - Ace Stream · Dockerized Ace Stream engine and its bundled dependencies.
- Engine API · Ace Stream server process exposing control and stream endpoints on port 6878.
- Stream cache · Continuous stream and peer/cache writes used during playback.
Release flow
Automation used to build and publish image artifacts.
- Hook build · Automated Docker build hook for CI or registry workflows.
hooks/build - Hook push · Automated Docker push hook for publishing tagged images.
hooks/push
External service
Runtime dependency outside the repository.
- Docker Hub · Prebuilt distribution target for the container image.
Connections 15
- 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.