Running AVideo with Docker

Running AVideo with Docker Compose

The repository includes a Docker Compose setup for AVideo, its Encoder, live streaming, databases and cache. Docker simplifies packaging, but you still need to understand DNS, HTTPS, backups, storage and updates before using it in production.

Docker or a direct dedicated-server installation?

Choice	Advantages	Tradeoffs	Good fit
Docker Compose	Packages services consistently, makes dependencies visible, and simplifies starting/stopping the complete stack	Requires Docker networking, volumes, logs, image updates, and resource limits to be understood	Testing, repeatable deployments, and administrators comfortable with containers
Direct installation on a VPS/dedicated server	Full control of Apache/PHP/database/FFmpeg/service tuning and direct access to host resources	More package/service configuration is performed manually	Production teams that manage Linux services directly
Managed/professional installation	Reduces setup mistakes and Linux learning required from the site owner	Service cost and a clear support/maintenance agreement are needed	Non-technical owners who want a working business platform

Docker does not make a small server faster or unlimited. The same CPU, RAM, disk, and bandwidth limits still apply. For larger workloads, compare a properly sized origin with AVideo CDN and CDN Storage.

What the Compose stack includes

Component	Purpose
AVideo web/Streamer service	Website, users, catalog, plugins, and playback pages
Encoder service	Processes uploaded source files into the configured formats/qualities
Separate database services	Store Streamer and Encoder records
Socket service	Supports real-time messages used by enabled features
Scheduled tasks	Runs supported recurring AVideo/Encoder work
Live server	Accepts and delivers configured live streams
Bind-mounted data under .compose	Keeps database/media/configuration data outside disposable container layers

Before you start

You need Docker with the Compose plugin, a domain name for public use, enough free disk space and permission to bind the selected ports. Run the commands from the root of the AVideo repository.

The current Compose file publishes web, WebSocket, WebRTC and live-streaming ports. Do not expose database or cache services publicly.

Ports documented by the Compose setup

The older guide documented these environment-variable defaults. Confirm them in the env.example and Compose file included with the exact release you install, because a release can change its mappings.

Variable/purpose	Documented default	Public?
HTTP_PORT	80	Normally public for redirect/certificate validation
HTTPS_PORT	443	Public website and media
SOCKET_PORT	2053	Public only when browsers connect directly instead of through the HTTPS proxy
NGINX_RTMP_PORT	1935	Reachable by authorized live broadcasters
NGINX_HTTP_PORT	8080	Restrict or proxy according to the live-server design
NGINX_HTTPS_PORT	8443	Restrict or proxy according to the live-server design
DB_MYSQL_PORT	3306	Private Docker/server network; do not expose publicly by default

WebRTC may publish additional TCP/UDP ports. Review the active Compose file and WebRTC plugin before creating firewall rules.

Environment variables explained

The env.example file is the authoritative template for the release you downloaded. Copy it to .env, then edit .env; do not edit the Compose file merely to change a normal variable.

Variable	What it controls	Historical/default example	What a beginner should do
SERVER_NAME	Public hostname used by the website/certificate setup	localhost	Set the real domain without http://, https://, or a path
CONTACT_EMAIL	Administrator/contact e-mail used by supported setup/services	admin@localhost	Use a monitored address on a real public deployment
WEBSITE_TITLE	Initial/public site title	AVideo	Replace with the name customers should see
MAIN_LANGUAGE	Main interface language/locale	en_US	Choose the locale used by the main audience
SYSTEM_ADMIN_PASSWORD	Initial system administrator credential	Old examples used password	Set a long unique password before starting; never keep the example
DB_MYSQL_HOST	Database hostname inside the Compose network	Commonly the database service name	Normally keep the template value unless the database design changes
DB_MYSQL_PORT	Database service port	3306	Keep private; do not publish it to the internet by default
DB_MYSQL_NAME	AVideo database name	avideo	Keep or change consistently with the database service
DB_MYSQL_USER	Dedicated AVideo database user	avideo	Use only for this database, not a global root account
DB_MYSQL_PASSWORD	Database password	Old examples used avideo	Replace with a strong unique secret before first start
CREATE_TLS_CERTIFICATE	Whether the included setup should create/configure TLS	Commonly yes	Use only with correct public DNS and the intended certificate workflow
TLS_CERTIFICATE_FILE	Certificate file path inside the expected container/mount	Template-specific	Change only when supplying a certificate through the documented mount/path
TLS_CERTIFICATE_KEY	Private certificate-key path	Template-specific	Protect it; never publish or commit the key
SOCKET_PORT	Host port for direct Socket access	2053	Publish only when browsers do not reach it through the HTTPS proxy
HTTP_PORT / HTTPS_PORT	Public website ports	80 / 443	Avoid conflicts and keep the advertised URLs/firewall consistent
NGINX_RTMP_PORT	Live broadcaster ingest	1935	Allow only the broadcasters/audience design that needs it
NGINX_HTTP_PORT / NGINX_HTTPS_PORT	Live-server web endpoints	8080 / 8443	Restrict or proxy according to the active live configuration

Historical defaults explain older guides; the current env.example wins when values differ. Any value containing a password, token, certificate key, or private hostname must be removed from screenshots and support messages.

Why SERVER_NAME matters

SERVER_NAME=video.example.com tells the stack which hostname users should open and which name a public certificate should cover. The DNS record must point to the server before automatic certificate validation can succeed.

For local testing, SERVER_NAME=localhost may create/use a certificate that browsers do not trust. That is not suitable evidence that public HTTPS is ready.

Start with one copy-and-paste block

Current Docker installations normally use docker compose with a space. Older installations may provide the legacy docker-compose command with a hyphen. They perform the same Compose role, but use the command that is actually installed on your server; the block below uses the current form.

cp -n env.example .env && \
${EDITOR:-nano} .env && \
docker compose up -d --build && \
docker compose ps && \
docker compose logs --tail=200

The command opens .env before starting. Review every value. At minimum:

• set SERVER_NAME to the public domain, without http:// or a path;
• set CONTACT_EMAIL to a working address;
• set a strong, unique DB_MYSQL_PASSWORD;
• set a strong, unique SYSTEM_ADMIN_PASSWORD;
• review CPU and memory limits for the host;
• review ports and NETWORK_SUBNET to avoid conflicts.

Do not commit or publish .env. It contains credentials. The values in env.example are examples, not production passwords.

If SYSTEM_ADMIN_PASSWORD is empty or literally password, the installer may generate one and record it in the container logs and videos/.initial_admin_password. Retrieve it promptly, sign in, change it, and protect or remove exposed copies.

The first build and database initialization can take time. The same block shows service status and recent logs when the startup step finishes. Then open the configured HTTPS address and test sign-in, upload/encoding and playback.

With SERVER_NAME=localhost, generated TLS is suitable for local testing and may cause a browser warning. A public installation needs correct DNS and a trusted certificate. Changing a port is not a substitute for HTTPS, strong passwords, updates and a firewall.

Where data is stored

The Compose setup uses bind-mounted data under .compose, including databases, videos, Encoder data, HLS and certificate data. The repository directory itself is also mounted into the AVideo container.

Stopping containers does not normally delete these files. However, deleting or replacing .compose can remove the site's databases and media. Do not run docker compose down -v, cleanup utilities or manual deletion until you have confirmed exactly which data will be removed.

Backups

A useful backup must include:

• database dumps from both database services;
• .compose/videos, .compose/encoder, .compose/HLS and certificate data as applicable;
• .env stored securely;
• any local source, plugin or theme changes.

Copying a live database directory is not the same as a consistent database dump. Test restoration on another host. See How to make a backup.

Routine commands

Each row is a separate task. Copy only the one command you need.

Task	One-line command
See service status	docker compose ps
View recent logs	docker compose logs --tail=200
Restart the AVideo service	docker compose restart avideo
Stop the stack without deleting its data	docker compose down

Use the service name shown by docker compose ps when inspecting a specific component.

Updating

1. Read the release notes.
2. Back up and test the backup.
3. Record the current image/container status.
4. Run git pull in the AVideo repository. If tracked local modifications block it, follow Update AVideo to discard them and restore the official remote files.
5. Rebuild and start with docker compose up -d --build.
6. Run any offered AVideo database updates, update plugins, and install their new tables.
7. Watch the logs and test sign-in, playback, upload, Encoder and live features.

Keep deployment-specific values in .env and the documented data directories instead of modifying tracked application files. This allows normal updates to remain a simple git pull.

Common problems

A port is already in use: find the existing service and decide which application should own the port. If you remap a port, also update firewall, proxy and advertised URLs as necessary.

A container is unhealthy: run docker compose ps and inspect that service's logs. Database initialization, wrong .env values and insufficient memory are common causes.

The Encoder cannot find the Streamer: inside a container, localhost means that container. Use the service/public address intended by the Compose setup and see the Encoder connection guide.

Uploads disappear after recreating containers: confirm that the .compose bind mounts exist, are writable and were not replaced.

HTTPS does not work: verify public DNS, ports 80/443, certificate settings and logs. Do not permanently bypass certificate validation.

When requesting help, include docker compose ps, the relevant recent logs, Docker/Compose versions and a redacted list of environment variable names. Never post .env or database dumps publicly.