11notes/uosserver repository overview

⁠UOSSERVER

run Unifi OS server as a container

⁠INTRODUCTION 📢

Self‑hosted software package that delivers UniFi Network, and soon additional applications in the UniFi ecosystem, from a single install.

⁠CAUTION ⚠️

To run this image safely, since it needs access to certain resources of your host, run it via sysbox runtime and not the default Docker runtime if you are not using rootless runtimes! This image is in active development, there could be potential major changes on how this image handles volumes, data, etc!

⁠SYNOPSIS 📖

What can I do with this? This image will provide you a rock solid Unifi OS server image. This image breaks (currently) all container philosophies by running multiple containers inside this image that are managed by the Unifi OS Server. This means updates to the apps inside the image are handled by the Unifi OS Server, not the image. Only the Unifi OS Server image itself is handled by this image. Consider running a VM instead of a container for this.

⁠UNIQUE VALUE PROPOSITION 💶

Why should I run this image and not the other image(s) that already exist? Good question! Because ...

• ... this image is auto updated to the latest version via CI/CD
• ... this image has a health check
• ... this image is created via a secure and pinned CI/CD process

If you value security, simplicity and optimizations to the extreme, then this image might be for you.

⁠VOLUMES 📁

• /sys/fs/cgroup - Directory on your host to access cgroups
• /persistent - Directory of package manager
• /data - Directory of all application data
• /srv - Directory of service specific data
• /var/lib/unifi - Directory of Unifi Network Controller data
• /var/lib/mongodb - Directory of mongodb
• /etc/rabbitmq/ssl - Directory of self-signed SSL certificates for RabbitMQ

⁠COMPOSE ✂️

name: "unifi"
services:
  os-server:
    runtime: sysbox-runc
    cpus: "8.0"
    mem_reservation: "4G"
    mem_limit: "8G"
    image: "11notes/uosserver:5.1.42"
    cap_add:
      - NET_RAW
      - NET_ADMIN
    cgroup: host
    environment:
      TZ: "Europe/Zurich"
      UOS_SYSTEM_IP: "${IP}"
    volumes:
      - "/sys/fs/cgroup:/sys/fs/cgroup:rw"
      - "os-server.var:/persistent"
      - "os-server.log:/var/log"
      - "os-server.data:/data"
      - "os-server.srv:/srv"
      - "os-server.lib:/var/lib/unifi"
      - "os-server.db:/var/lib/mongodb"
      - "os-server.rabbitmq.ssl:/etc/rabbitmq/ssl"
    tmpfs:
      - "/run:exec"
      - "/run/lock"
      - "/tmp:exec"
      - "/var/lib/journal"
      - "/var/opt/unifi/tmp:size=64m"
    ports:
      - 443:443
      - 5005:5005
      - 5671:5671
      - 6789:6789
      - 8080:8080
      - 8443:8443
      - 8444:8444
      - 8880:8880
      - 8881:8881
      - 8882:8882
      - 9543:9543
      - 11084:11084
      - 3478:3478/udp
      - 5514:5514/udp
      - 10003:10003/udp
    networks:
      frontend:
    sysctls:
      net.ipv4.ip_unprivileged_port_start: 443
    restart: "always"

volumes:
  os-server.var:
  os-server.log:
  os-server.data:
  os-server.srv:
  os-server.lib:
  os-server.db:
  os-server.rabbitmq.ssl:

networks:
  frontend:

To find out how you can change the default UID/GID of this container image, consult the RTFM⁠.

⁠DEFAULT SETTINGS 🗃️

⁠ENVIRONMENT 📝

⁠MAIN TAGS 🏷️

These are the main tags for the image. There is also a tag for each commit and its shorthand sha256 value.

• 5.1.42⁠

⁠There is no latest tag, what am I supposed to do about updates?

It is my opinion that the :latest tag is a bad habbit and should not be used at all. Many developers introduce breaking changes in new releases. This would messed up everything for people who use :latest. If you don’t want to change the tag to the latest semver⁠, simply use the short versions of semver⁠. Instead of using :5.1.42 you can use :5 or :5.1. Since on each new version these tags are updated to the latest version of the software, using them is identical to using :latest but at least fixed to a major or minor version. Which in theory should not introduce breaking changes.

If you still insist on having the bleeding edge release of this app, simply use the :rolling tag, but be warned! You will get the latest version of the app instantly, regardless of breaking changes or security issues or what so ever. You do this at your own risk!

⁠REGISTRIES ☁️

docker pull 11notes/uosserver:5.1.42
docker pull ghcr.io/11notes/uosserver:5.1.42
docker pull quay.io/11notes/uosserver:5.1.42

⁠SOURCE 💾

• 11notes/uosserver⁠

⁠PARENT IMAGE 🏛️

• [11notes/uosserver:fw-5.0.6](${{ json_readme_parent_url }})

⁠BUILT WITH 🧰

• uosserver⁠
• 11notes/util⁠

⁠GENERAL TIPS 📌

• Use a reverse proxy like Traefik, Nginx, HAproxy to terminate TLS and to protect your endpoints
• Use Let’s Encrypt DNS-01 challenge to obtain valid SSL certificates for your services

⁠ElevenNotes™️

This image is provided to you at your own risk. Always make backups before updating an image to a different version. Check the releases⁠ for breaking changes. If you have any problems with using this image simply raise an issue⁠, thanks. If you have a question or inputs please create a new discussion⁠ instead of an issue. You can find all my other repositories on github⁠.

created 11.09.2026, 06:12:13 (CET)