A plug-and-play Docker image that turns the official OpenCloud server into a genuine one-click Unraid app: it runs the required first-boot init for you, heals the appdata permissions and honours Unraid's PUID/PGID — no console, no chown, no config-file editing required.

Table of Contents

1. Overview
2. Quick Start
3. Configuration
4. Production vs Rolling
5. How the Wrapper Works
6. Reverse Proxy
7. Building Locally
8. Updating
9. Troubleshooting
10. Architecture
11. Contributing / License
12. Support this project

1. Overview

OpenCloud is a modern, self-hosted file sync-and-share platform (an actively developed member of the ownCloud/Infinite-Scale family). The official opencloudeu/opencloud image is excellent, but it is not built for a one-click NAS install:

• it runs its binary as a fixed UID with no PUID/PGID support, so on a fresh Unraid box the root-owned bind mounts make the very first boot fail with "permission denied" writing /etc/opencloud/opencloud.yaml and /var/lib/opencloud/nats;
• it requires a one-time opencloud init to be run by hand before opencloud server will start.

This image is a thin wrapper around the official one that fixes exactly those two things and nothing else:

• Auto-init — runs opencloud init once on first boot (idempotent on later boots).
• Permission heal — creates the config/data dirs and hands them to your PUID:PGID, and repairs a previously root-owned tree once (sentinel-guarded, so it never recursively re-chowns your whole data set on every start).
• PUID / PGID — drops privileges to Unraid's nobody:users (99:100) by default via a static gosu.
• Two channels — :production (stable, default) and :rolling (newest builds), from the same wrapper.
• Multi-arch — amd64 and arm64.

The wrapper does not fork, patch or repackage OpenCloud itself — it layers a tiny entrypoint on top of the unmodified upstream image, so you always run real, current OpenCloud.

The OpenCloud web UI: your personal space with files, folders and spaces.

Sign in as admin with the password you set in the Unraid template.

2. Quick Start

Step 1 — Install the template

On Unraid: Apps → search for OpenCloud → Install. The Community Applications template is published from the unraid-apps feed.

To load it by hand:

mkdir -p /boot/config/plugins/dockerMan/templates-user && \
curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-OpenCloud.xml \
  https://raw.githubusercontent.com/junkerderprovinz/unraid-apps/main/opencloud/opencloud.xml

Step 2 — Set the admin password and paths

In the template, the only field you must set is Admin Password (IDM_ADMIN_PASSWORD) — it becomes the password for the built-in admin user on first start. The two volumes default to /mnt/user/appdata/opencloud/{config,data}; adjust the data path to a share with room to grow.

Step 3 — Start and wait for the banner

Hit Apply. The first start takes a moment while the container generates its config and a self-signed certificate. Watch the container log for:

  OpenCloud
  OPENCLOUD IS READY

Step 4 — Open the WebUI

Open https://<unraid-ip>:9200/ and accept the self-signed certificate once. Log in as admin with the password you set.

docker run -d \
  --name opencloud \
  --restart unless-stopped \
  -p 9200:9200 \
  -e PUID=99 -e PGID=100 \
  -e IDM_ADMIN_PASSWORD='change-me-please' \
  -e OC_URL='https://192.168.1.10:9200' \
  -e OC_INSECURE=true \
  -v /mnt/user/appdata/opencloud/config:/etc/opencloud \
  -v /mnt/user/appdata/opencloud/data:/var/lib/opencloud \
  junkerderprovinz/opencloud:production

3. Configuration

No database. OpenCloud is not Nextcloud — it has no MySQL/Postgres and needs none. State lives in the decomposed metadata tree on the /var/lib/opencloud volume plus an embedded NATS bus. Don't add a database container; there's nothing to point it at.

S3 object storage (optional)

OpenCloud can keep file blobs in any S3-compatible bucket (MinIO, AWS S3, Backblaze B2, Wasabi) while the metadata stays local. Set the storage driver to decomposeds3 and add the connection variables — leave them unset for normal local storage.

Where those values come from:

• MinIO (self-hosted). In the MinIO console click Create Bucket (top left) and name it (e.g. opencloud) — that is your bucket name. The current MinIO Community Edition console has no Access Keys page (only the object browser), so for the keys either:

  • Easiest: use your MinIO root credentials directly — access key = MINIO_ROOT_USER, secret key = MINIO_ROOT_PASSWORD (the values you set on your MinIO container; check its Docker template).
  • Cleaner (dedicated, revocable key): create a service account with the mc CLI — mc alias set my http://<minio-ip>:9000 <root-user> <root-pass> then mc admin user svcacct add my <root-user>, which prints a fresh Access Key + Secret Key.

  Point the endpoint at the API port http://<minio-ip>:9000 (not the 9001 console) with region default.

• AWS S3 / Backblaze B2 / Wasabi. Create a bucket in the provider console, then create an access key (AWS: an IAM access key; B2/Wasabi: an application/API key). Use the provider's https:// endpoint and the bucket's region.

The metadata always stays local. decomposeds3 puts only the blob bytes in S3; the file tree, xattrs and the blob→object mapping live on /var/lib/opencloud. That volume is therefore required and must be backed up even with S3 — losing it orphans your S3 objects (they are opaque IDs with no folder structure). There is no all-on-S3 mode. OpenCloud's system/metadata store (STORAGE_SYSTEM_DRIVER) stays decomposed (local) and needs no change.

MinIO note: if uploads fail with a checksum error on a non-AWS endpoint, add STORAGE_USERS_DECOMPOSEDS3_PUT_OBJECT_DISABLE_CONTENT_SHA256=true. This wrapper's S3 path is verified end-to-end against MinIO (blob lands in the bucket, metadata on the local volume).

4. Production vs Rolling

Two channels are built from this wrapper, differing only in the upstream base image:

Switch by changing the Repository tag in the Unraid template (:production → :rolling). Back up your appdata before switching channels. Renovate keeps both base pins current, and the weekly rebuild picks up upstream and Alpine security patches.

5. How the Wrapper Works

The entrypoint runs as root only long enough to prepare the volumes, then drops to your user:

1. Permission heal. Creates /etc/opencloud + /var/lib/opencloud if missing and chowns them to PUID:PGID. The config dir is small and always fully healed; the data dir is only chown -R'd once (or after a PUID/PGID change), tracked by a .uid-heal sentinel — so a large data set is never recursively re-owned on every boot. The nats bus dir is always re-asserted (small, must stay writable).
2. Init. Runs opencloud init as the target user (writes opencloud.yaml, consuming IDM_ADMIN_PASSWORD). Idempotent — it harmlessly errors once the config exists.
3. Hand-off. Prints the ready banner, then execs opencloud server dropped to PUID:PGID via a static gosu (copied from the upstream tianon/gosu image — no package manager needed in the base).

6. Reverse Proxy

By default OpenCloud serves HTTPS itself on 9200 with a self-signed certificate — ideal for a direct LAN install. To put it behind a reverse proxy that terminates TLS (Traefik, NGINX Proxy Manager, SWAG, …):

• set PROXY_TLS=false (OpenCloud then serves plain HTTP for the proxy to wrap),
• set OC_URL to your external URL, e.g. https://cloud.example.com,
• set OC_INSECURE=false (your proxy presents a valid certificate),
• point the proxy upstream at the container's port 9200.

Desktop or mobile client login returns 403 Forbidden while the browser works? The native clients sign in through a loopback OIDC redirect (redirect_uri=http://127.0.0.1:<port>, per RFC 8252). Many reverse-proxy "block exploits" filters reject a literal http:// inside a query string. In NGINX Proxy Manager this is the "Block Common Exploits" toggle: its block-exploits.conf contains if ($query_string ~ "[a-zA-Z0-9_]=http://") { return 403; }. The web UI avoids it (its redirect is URL-encoded), the desktop client trips it (plain http:// loopback). Switch that toggle off for the OpenCloud host and the client login succeeds. OpenCloud brings its own auth and CSRF protection, so the crude regex filter is redundant here.

7. Building Locally

git clone https://github.com/junkerderprovinz/opencloud.git
cd opencloud

# production channel (default base pin)
docker build -t opencloud:dev .

# rolling channel (reads the BASE_ROLLING pin from the Dockerfile)
docker build --build-arg BASE="$(grep -oE 'ARG BASE_ROLLING=[^[:space:]]+' Dockerfile | cut -d= -f2)" -t opencloud:rolling .

# multi-arch (amd64 + arm64) — needs buildx
docker buildx build --platform linux/amd64,linux/arm64 -t opencloud:dev --load .

just recipes mirror the CI flows — just build, just build-rolling, just smoke, just lint.

8. Updating

docker pull junkerderprovinz/opencloud:production
docker stop opencloud && docker rm opencloud
# re-create with the same template / docker run args

On Unraid: Docker tab → the container → Force Update. Your /etc/opencloud and /var/lib/opencloud are untouched. The image is rebuilt weekly for upstream OpenCloud and Alpine patches.

9. Troubleshooting

Crash loop with search: cannot open index, metadata missing

The container starts, heals ownership, then crash-loops and the WebUI never comes up. This means the Data volume is pointing at a non-fresh OpenCloud/oCIS data directory — an old install, or a data set created with a different storage backend (local vs S3). The layouts are not interchangeable and there is no in-place migration between backends, so the search service can't open its index and takes the whole server down.

Fix: give it a fresh, empty Data folder. Move the old directory aside (mv /mnt/user/opencloud /mnt/user/opencloud.old) and let a new empty one be created, then restart. To keep old files, start fresh and re-upload them through the web UI. This is not a bug in the wrapper or the image — a clean data dir boots normally, S3 included.

10. Architecture

┌──────────────────────────────────────────────────────────────┐
│  opencloudeu/opencloud[:production] | opencloud-rolling        │
│  (Alpine base + the OpenCloud binary, unmodified)             │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  entrypoint.sh  (runs as root)                          │  │
│  │   ↓ mkdir + chown /etc/opencloud, /var/lib/opencloud    │  │
│  │   ↓ one-time data heal (sentinel-guarded)               │  │
│  │   ↓ gosu PUID:PGID  opencloud init  (|| true)           │  │
│  │   ↓ print "OPENCLOUD IS READY" banner                   │  │
│  │   ↓ exec gosu PUID:PGID  opencloud server               │  │
│  └────────────────────────────────────────────────────────┘  │
│      static gosu  ← COPY --from=tianon/gosu (multi-stage)     │
└──────────────────────────────────────────────────────────────┘

11. Contributing / License

Pull requests welcome. Issues: https://github.com/junkerderprovinz/opencloud/issues.

Licensing — dual:

• This wrapper repository (Dockerfile, entrypoint.sh, print-banner.sh, Unraid template, README and banner/icon artwork) is licensed under the MIT License.
• OpenCloud itself and the bundled gosu binary are Apache-2.0; the Alpine base and its packages keep their own licenses. When you run, redistribute or rebuild the resulting image you must comply with all of those, not only this wrapper's MIT license. See NOTICE.

The OpenCloud logo and wordmark are the property of OpenCloud GmbH, used unmodified to identify the upstream project. This is an independent, community-maintained packaging and is not affiliated with or endorsed by OpenCloud GmbH.

Credits

• OpenCloud — the file sync-and-share platform this image wraps
• gosu — clean, static privilege-drop for the entrypoint

12. Support this project

If this template saves you a setup hassle or a debug night, consider buying me a coffee: