Thank you for your interest in contributing to the UHF Server Docker project! This document provides guidelines and steps for contributing.
Contributions here cover the Docker image, bundled dependencies, Compose configuration, and setup documentation. UHF app and server bugs or product feature requests belong with UHF support. Running UHF in this container does not make a product bug a Docker packaging bug.
Read Support and issue scope before opening an issue or proposing a change.
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
This project uses semantic versioning.
Version numbers will be assigned by maintainers after merge, so you don't need to update version numbers in your PR.
When submitting a PR:
- Document your changes in
CHANGELOG.mdunder a temporary heading (e.g., "## Unreleased") - Note any breaking changes in your PR description
- The maintainers will handle version bumps, tagging, and changelog organization after merging
# Build a local image for the current architecture
source .dev/versions.env
docker buildx build --load \
--build-arg UHF_VERSION="$UHF_VERSION" \
--build-arg FFMPEG_VERSION="$FFMPEG_VERSION" \
-f Dockerfile.uhf \
-t "solidpixel/uhf-server:uhf-${UHF_VERSION}-ffmpeg${FFMPEG_VERSION}-${DOCKER_REVISION}" .
# Start the local image using Compose
docker compose up -d
# Test the container
curl http://localhost:8000/server/statsAlso open http://localhost:8000/ and verify the browser interface. Test recordings and password login with a separate data directory before releasing. The build verifies that the installed FFmpeg version matches FFMPEG_VERSION; update it and the image tag together when Debian updates FFmpeg.
The project uses separate scripts for preparing and tagging releases:
# 1. First update versions in .dev/versions.env
vim .dev/versions.env
# 2. Prepare release (updates badges, docker-compose.yml, and changelog)
./.dev/prepare-release.sh
# The script will pause for you to edit the changelog manually.
# 3. Open a pull request and merge it.
# 4. Build and push Docker images (must be done before tagging)
./.dev/build-docker.sh
# 5. After images are online and verified, create and push the Git tag
./.dev/tag-release.sh
# 6. Publish the matching GitHub releaseThe scripts handle different parts of the release process:
prepare-release.shupdates documentation, badges, docker-compose.yml, and adds a changelog entrybuild-docker.shbuilds and pushes multi-arch Docker images (before tagging)tag-release.shcreates and pushes the Git tag (after Docker images are online and verified); publish the GitHub release from that tag
Docker images are pushed with these tags:
solidpixel/uhf-server:latestsolidpixel/uhf-server:<IMAGE_TAG>(where<IMAGE_TAG>includes UHF version, FFmpeg version, and optional Docker revision, e.g.,uhf-1.3.0-ffmpeg7.1.1-d1)
- Include a clear description of the changes
- Update documentation as needed
- Add appropriate labels
- Reference any related issues
Format your commit messages as follows:
- For documentation:
docs: Update installation guide - For build changes:
build: Update Dockerfile dependencies - For general changes:
chore: Update .gitignore - For features:
feat: Add new environment variable - For fixes:
fix: Correct port mapping
# Changes that need Docker rebuild:
git commit -m "build: Update Dockerfile dependencies"
# Changes that don't need Docker rebuild:
git commit -m "docs: Update installation guide"Open an issue for Docker packaging bugs, improvements to this repository, or questions about the documented Docker Compose setup. Include the image tag, host environment, steps to reproduce, and relevant logs when reporting a bug. Remove passwords, tokens, stream URLs, and other private information.
For recording logic, playback, scheduling, server logging, native installations, or account and subscription issues, contact UHF support. Upstream product reports may be closed here with a referral to UHF support.