Uncloud Files

This release brings shared TLS certificate storage for Caddy, systemd socket activation, runtime templates, and a way to use your own cluster domain. It also adds a certificate inventory command, faster service listing, and fixes for proxying, container logs, and terminal output.

⚠️ Breaking changes

• The API socket moved from /run/uncloud/uncloud.sock to /run/uncloud/api/uncloud.sock (f68c985). Update your custom tools and container mounts if you used the API socket directly. Both old and new uc versions handle the socket move automatically.

Shared certificate storage for Caddy

Caddy module: caddy-uncloud, issue: #31

If you run Caddy on multiple machines behind a load balancer or a DNS record with multiple IPs, certificate issuance may not work correctly.

The new Uncloud storage module lets Caddy instances share certificates, private keys, and challenge tokens through the cluster store. Any instance can read the token to answer a challenge, and once one obtains a certificate, the others can use it too. Distributed locks coordinate issuance across machines.

Shared storage is opt-in for now. See Cluster storage for Caddy for more details.

Inspect Caddy certificates

Changes: 930e7ea, 9c21ae6

The new uc caddy cert ls command lists certificates in Caddy's shared cluster storage. This is handy for checking which certificates have been issued and when they expire.

:::shell
uc caddy cert ls
uc caddy cert ls --machine machine-1
uc caddy cert ls -o json

This requires Caddy to first be deployed with cluster storage.

Systemd socket activation

Change: f68c985

Systemd now creates the Uncloud API socket and passes it to the daemon when it starts. The socket is available before Docker starts and stays in place across daemon restarts. This gives Caddy's cluster storage module and other extensions a stable API socket, including after a reboot.

Runtime templates for bind mounts

Change: 5c33e4b

You can now use per-container metadata in bind mount paths. Uncloud renders these Go templates on the destination machine just before creating each container, so every replica can get its own host directory:

:::yaml
services:
  app:
    image: app:latest
    scale: 2
    volumes:

      - "/var/lib/app/{{.Container.Name}}:/data"

For now, runtime templates expose .Container.Name and work only in the host and container paths of bind mounts. They could easily be extended to other metadata fields and Compose attributes. Please share your use case on #431.

See Runtime templates for more details and examples.

Use your own cluster domain

PR: #365. Thanks to @miekg for the contribution ❤️

The new uc dns set command lets you use a domain you manage yourself as the default cluster domain for generated service hostnames:

:::shell
uc dns set apps.example.com

Configure wildcard DNS records for *.apps.example.com with your DNS provider, pointing to machines running Caddy. New services published without an explicit hostname can then use addresses like web.apps.example.com. Uncloud doesn't create or manage those external records.

If your cluster already has a reserved *.uncld.dev domain, release that reservation with uc dns release first.

Improvements

• uc ls now collects services and containers with a single broadcast request instead of inspecting every service separately. This significantly speeds it up, especially when you have many services (0e53f50).
• Compose now supports stdin_open and tty (#419). Thanks to @miekg for the contribution ❤️
• Compose warns about more unsupported options, including external configs, container_name, and deploy.placement (#429). Thanks to @miekg for the contribution ❤️
• uc machine init/add now accept UNCLOUD_DAEMON_VERSION as an alternative to --version, useful for scripts and nightly setups (#409). Thanks to @tonyo for the contribution ❤️
• Caddy deployments now have a healthcheck that queries the admin API, so the deployment waits for Caddy to load its config before treating a new container as healthy (70de7b1).
• The installation docs now include mise (#421).

Bug fixes

• Preserve custom global Caddy configuration during regeneration on Caddy restart. uc caddy config now warns when the last attempt to load the config failed (ace8cbf).
• Keep uc proxy running when an individual client disconnects or a forwarded connection fails. Connection errors now include more useful troubleshooting information (fa77edf).
• Stream logs correctly from containers with an allocated TTY (#419).
• Stop terminal capability replies from leaking into the shell after CLI spinners finish (#435). Thanks to @tonyo for the contribution ❤️
• Fix shell completion when using --connect, --context, or --uncloud-config (351698c).
• Return a non-zero exit code consistently when a command is cancelled by declining a confirmation prompt (#406). Thanks to @miekg for the contribution ❤️
• Extend the systemd startup timeout while pulling the Corrosion image, allowing up to 5 minutes for a slow pull (dc721e5).
• Fix daemon version comparisons when upgrading from a nightly build to the latest stable release (50f8fbc).
• Avoid waiting on replication gaps from unavailable cluster members after the requested store versions have been reached (e4bd1ad).

Upgrade to v0.21.0

Upgrade your local CLI and the daemon on every machine. If you're upgrading from before v0.20.0, follow the v0.20.0 upgrade instructions first for the Corrosion migration.

Uncloud CLI locally

:::bash
# Homebrew (macOS, Linux)
brew upgrade uncloud

# Install script (macOS, Linux)
curl -fsS https://get.uncloud.run/install.sh | VERSION=0.21.0 sh

Machine daemon

Run the following commands over SSH on each machine to upgrade the daemon binary:

:::bash
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL -o uncloudd.tar.gz https://github.com/psviderski/uncloud/releases/download/v0.21.0/uncloudd_linux_${ARCH}.tar.gz
tar -xf uncloudd.tar.gz
sudo install uncloudd /usr/local/bin/uncloudd
rm uncloudd uncloudd.tar.gz

The following systemd unit updates are only needed on existing machines. New machines set up with uc machine init or uc machine add using v0.21.0 or later install these units automatically. Replacing the daemon binary alone on an existing machine doesn't install the new uncloud.socket unit or update uncloud.service.

Create /etc/systemd/system/uncloud.socket:

:::bash
sudo tee /etc/systemd/system/uncloud.socket >/dev/null <<'EOF'
[Unit]
Description=Uncloud API socket
Before=docker.service

[Socket]
ListenStream=/run/uncloud/api/uncloud.sock
SocketUser=root
SocketGroup=uncloud
SocketMode=0660
DirectoryMode=0750

[Install]
WantedBy=sockets.target
EOF

Run this command to add the socket dependency directly to /etc/systemd/system/uncloud.service:

:::bash
sudo sed -i \
  's/^After=network-online.target docker.service$/Requires=uncloud.socket\
After=network-online.target uncloud.socket docker.service/' \
  /etc/systemd/system/uncloud.service

Stop the daemon before starting the socket unit, then reload systemd, enable the socket, and start the upgraded daemon:

:::bash
sudo systemctl stop uncloud.service
sudo systemctl daemon-reload
sudo systemctl enable uncloud.socket
sudo systemctl start uncloud.service

After upgrading

Check your CLI and daemon versions:

:::shell
uc version
uc machine ls

Changelog

• [f68c98] BREAKING CHANGE: move Uncloud API socket to /run/uncloud/api/uncloud.sock, activate it by systemd socket unit
• [ad2e1a] Ignore domain when there is no endpoint
• [81d36e] No need to call out to update anything, as set doesnt use uncloud dns
• [3fc1cd] Rebase and and generate protos again
• [b28c45] Rebase and fix
• [5fb80e] check validatity
• [c58108] chore(.editorconfig): ignore formatting for release notes
• [abb85f] chore(AGENTS): do not emphasize the importance of table driven tests
• [37f817] chore(caddystorage): adjust log levels
• [4dae18] chore(caddystorage): move storage module code to a separate unlabs-dev/caddy-uncloud repo
• [6b4134] chore(cli): use cli.Cancelled when cancellikng the command to return non-zero exit code in all cases (#406)
• [ebecf3] chore(dns): require minimum server version 0.21
• [af2776] chore(dns): require minimum server version 0.21.0 for 'uc dns set' command
• [f15552] chore(docs): update command outputs in Deploy demo app doc, add section to view logs
• [796427] chore(experiments): go mod tidy
• [88dda4] chore(gitignore): ignore /research dir
• [6266e9] chore(nightly-build): prettier warning in description (#410)
• [b9c54f] chore(website): configure ingress Caddy as trusted proxy to forward client IPs
• [e525bd] chore(website): update discord members
• [db55df] chore: bump caddy Go pkg dependency to v2.11.4
• [3482ee] chore: go mod tidy
• [e81e13] chore: go mod tidy
• [e9e7b3] chore: move legacy unused WG tunnel and client connector to experiment/wg
• [d1fe23] docs
• [5d7952] docs(README): list cluster storage for certificates in features
• [87e99a] docs(caddy): new page Cluster storage for Caddy
• [f78a8c] docs(caddy): regenerate CLI reference for 'caddy cert ls' command
• [4b9ea4] docs(cli): update machine init/add help with info about installing Docker and uncloudd
• [c2ae11] docs(cluster): add section about SSH user permissions when connection to the cluster
• [ac5675] docs(install): mise installation (#421)
• [3af993] docs(install): update Debian repository domain (#413)
• [a1957a] docs(install): update machine init/add output that doesn't install corrosion systemd service
• [45d33d] docs(runtime-templates): add 'Added in v0.21.0' note
• [9c21ae] feat(caddy): CLI command to list certificates stored in the Uncloud cluster storage for Caddy
• [930e7e] feat(caddy): add ListCertificates method, refactor Caddy client layout (#31)
• [70de7b] feat(caddy): add healthcheck to default Caddy spec and Compose deployment in docs
• [bc0995] feat(caddy): mount uncloud API socket for storage module (#31)
• [c7e0e3] feat(caddystorage): define CaddyStorage gRPC service API for distributed Caddy storage
• [a24fc1] feat(caddystorage): generic namespace-scoped key-value storage using cluster table in Corrosion
• [7a8886] feat(caddystorage): implement the machine-local CaddyStorage gRPC service
• [9a4098] feat(caddystorage): init Caddy storage module backed by an Uncloud cluster
• [c6d037] feat(caddystorage): integrate CaddyStorage gRPC service in machine API
• [1e471d] feat(caddystorage): lint
• [f7be7c] feat(caddystorage): minor logging formatting
• [992b81] feat(caddystorage): simplify CaddyStorage gRPC API to allow only one2one calls
• [6ab02f] feat(caddystorage): simplify active locks tracking and cleanup
• [7c4fcd] feat(cli): support env var UNCLOUD_DAEMON_VERSION to specify daemon version for "uc machine add/init" (#409)
• [b7e224] feat(compose): support stdin_open and tty (#419)
• [7a7a31] feat(distlock): add gRPC Lease server that adapts a machine-local Store
• [3f86b3] feat(distlock): add integration tests for grpc transport
• [01426c] feat(distlock): add smoke e2e test for distributed lock (lease) in cluster
• [5a956e] feat(distlock): declare Lease gRPC service API for distributed locks
• [43bf2b] feat(distlock): implement distributed Locker based on Redlock algorithm
• [a5ab6e] feat(distlock): implement in-memory lease store
• [1c29d4] feat(distlock): integrate distributed lease management into Machine API
• [613cd6] feat(distlock): refactor into a standalone package
• [9ee3ca] feat(dns): allow setting an externally managed cluster domain
• [417e40] feat(dns): allow setting an externally managed cluster domain (uc dns set)
• [5c33e4] feat(runtime-templates): add support for runtime templates in bind mounts (#412)
• [0f6c03] feat(store): add WaitForStoreVersion API to wait for cluster store replication up to target version
• [e4bd1a] feat(store): improve waiting for store replication to skip unavailable members
• [cec3c7] feat: add uc dns set
• [aaf676] feat: validate remaining unsupported items of the support-matrix (#429)
• [ace8cb] fix(caddyconfig): custom global Caddy config is preserved on regeneration,warn about last load error in 'uc caddy config' (fixes [#412])
• [751ea9] fix(caddystorage): error formatting
• [351698] fix(cli): completion with direct connections (--connect, --context, --uncloud-config) (fixes [#377])
• [e4455e] fix(cli): stop leaking terminal capability replies into the shell (#435)
• [5e01db] fix(compose): remove unnecessary warning validating deploy.mode that is error
• [dc721e] fix(daemon): extend systemd service start timeout when pulling Docker image for corrosion service
• [d36b28] fix(docs): version command instead of --version in docs (#408)
• [e5f23a] fix(install): allow to install uc CLI version <0.20 after the artifact renaming
• [50f8fb] fix(install): correctly compare installed nightly daemon version to upgrade to latest
• [fa77ed] fix(proxy): don't shutdown 'uc proxy' when a client connection aborts
• [ae940c] fix(test): flaky distributed lock tests by waiting for WG mesh to become ready
• [47a4a9] from main
• [25ca0a] lint
• [54a732] mise proto && make cli-docs
• [e50c5f] refactor(api): replace map[string]uint64 with api.StoreVersion for store version handling
• [00d68d] refactor(client): make ProxySingleMachineContext and ProxyMachinesContext package functions as well
• [0e53f5] refactor(client): speed up service list call (N -> 1 broadcast RPC)
• [8aedc2] refactor(proto): move protobuf generated API to the top-level api/pb package
• [842f79] refactor(store): unify logic and enhance logging for initial store sync (waitStoreSync)
• [c65f35] test(connector): test UnixConnector reconnects after socket replacement
• [d670d1] website: add new Hub page
• [054b3b] website: change CTA link to getting started docs
• [b3896f] website: minor
• [4ad4bc] website: refine FAQ and form on hub page
• [4d76dd] website: refine faq open source question, update og image
• [e68479] website: refine styles for index and hub
• [f8e6d1] website: send Hub early access form submission to posthog
• [0007f7] website: serve hub as /hub
• [08b24a] website: split newsletter subscription into a separate section
• [b99abb] website: update docs social card and favicons
• [5b2823] website: update meta/og tags and images