Skip to content
SHC Docs

Step 5: Nextcloud on Postgres and S3

New line, in development. Installed on a four-node test cluster built from shc next b43f0c168 (ce 5db649eb) on 2026-10-08, with an S3 server on the cluster in place of the B2 bucket: a Versity S3 Gateway, connected with the same connection connect and connection grant as below, its own address as the endpoint and its own key. The run named that connection s3fix where this page says b2, and its bucket nextcloud. The output below is that run’s, trimmed.

Nextcloud is a catalog app with many plugs. This step binds two of them:

PlugRequiredWhat it wants
postgresunless --var postgres.hostname=... names an external server, or --var backend=mysql moves Nextcloud to the mysql pluga database and a user, as in step 4
s3no, --var s3.endpoint=... also names an S3 server directlya bucket; Nextcloud keeps its files in it, since S3 primary storage is native to Nextcloud

The others (oidc, smtp, imap, onlyoffice, paperless and more) are optional: a plug file with no required: line is optional (ce modules/app/plug_required.go).

Leave the s3 plug out and Nextcloud keeps its files on the server’s disk, in the nextcloud-data volume, and its backup carries them.

The catalog has no S3 server. The bucket comes from a hosted provider, here Backblaze B2, through a connection, and Nextcloud’s s3 plug binds straight to that connection. Object storage for apps is the full page, including the external-s3 front, which checks the bucket before an app starts; this step is the short path.

Make two things in the B2 console. SHC makes neither.

  1. A bucket. B2 bucket names are global, so nextcloud is taken: pick a name of your own. This page writes it <bucket>.
  2. An application key restricted to that one bucket, with read and write access. B2 shows a keyID and an applicationKey, once.

Note the bucket’s region from its endpoint, for example us-west-004.

Terminal window
$ shc connection connect b2 --type s3 -t rig \
--cred s3_endpoint=s3.us-west-004.backblazeb2.com \
--cred region=us-west-004 \
--value-file b2.json
$ shc connection grant b2 -t rig --capability s3 --grantee rig --boundary '{"unscoped":true}'
  • connection connect stores the endpoint and the key pair in the vault as a connection named b2. s3_endpoint is the bare host, with no https:// and no port. Before it stores anything, SHC lists buckets with the key; a dead endpoint, an unknown key or a wrong secret refuses the connect (X400461HLDRCH, ce modules/connections/providers/s3hold/probe.go). A key the provider denies the bucket list is proven on a bucket it can list instead, named with --cred probe_bucket=<bucket>. b2.json holds {"access_key": "<keyID>", "secret_key": "<applicationKey>"}. A secret is never typed on the command line, where your shell history and the process list keep it, and --cred secret_key=<applicationKey> is refused (X400548CRDSEC). The secret comes from the file --value-file names, the flag shc vault set takes: one field is --cred secret_key=- --value-file b2.key; two fields are the JSON object in the file named by --value-file alone.
  • connection grant lets tenant rig use the connection’s s3 capability. {"unscoped":true} says in writing that the tenant’s apps get the connection’s own key, not a key SHC cut down. With no --boundary the grant is refused (X403922CONUNS). An unscoped grant serves every app bound to b2 this same key, so each can reach every bucket it reaches. Here the key is limited to one bucket, because you limited it at B2. A grant with --boundary '{"buckets":["<name>"]}' instead mints each app its own B2 key for those buckets, which needs a connection key allowed to writeKeys, deleteKeys, listKeys and listBuckets plus the object capabilities the app key gets (see the S3 connections guide).

Keep pg from step 2 installed. The install may run on any node: the postgres edge reads its provider’s socket from the replicated store, as in step 4. The s3 edge needs no deployment; the daemon serves it from the connection.

Terminal window
$ shc install nextcloud -s cloud -t rig -i postgres=pg -i s3=@b2 \
--var s3.bucket=<bucket> \
--expose 8082=nextcloud:80
installing stack "cloud"
cloud: starting
cloud: running
installed deployment "cloud"
exposure: lan
$ shc integration ls -t rig -e prod
CONSUMER STACK NAME CONSUMER PLUG PROVIDER STACK NAME PROVIDER SOCKET STATUS ID
cloud postgres pg postgres connected 0
cloud s3 s3 connected 28
$ curl -s http://<node address>:8082/status.php
{"installed":true,"maintenance":false,"needsDbUpgrade":false,"version":"34.0.2.1","versionstring":"34.0.2","edition":"","productname":"Nextcloud","extendedSupport":false}

The s3 edge has no provider stack: its provider is the connection. On the test cluster the install took about three and a half minutes, and once Nextcloud was up its bucket held 66 objects: the files it keeps from its first start.

  • -i postgres=pg is step 4’s edge: the Postgres socket makes Nextcloud its own database and user.
  • -i s3=@b2 binds the s3 plug to the connection b2. The @ names a connection, not a stack. An s3 connection serves the s3 capability: the key it holds. An aws connection would serve s3-bucket instead and make a bucket and a key for the app (ce modules/app/mint_seam.go, capabilitiesForPlug).
  • --var s3.bucket=<bucket> names the bucket you made. With a held key SHC keeps the app’s own bucket, and the package’s default is nextcloud, which is not yours at B2.
  • There is no key variable to set. The package defaults s3.accessKey and s3.secretKey to a key of Nextcloud’s own, and on a connection edge SHC writes the connection’s key pair over them (ce modules/app/integration_render.go, stampEdgeCredentials). A non-empty --var s3.accessKey=... of yours would still win.
  • --expose 8082=nextcloud:80 publishes the container’s port 80 on port 8082 of the node.
  1. It resolves both edges. For s3=@b2 the daemon checks that b2 is granted to rig for s3, or refuses with X403910CONGRT. It then asks the connection’s s3 capability for the endpoint, port 443, region, the key pair and TLS on, and puts exactly those under the plug’s socket data. It writes the key pair over the plug’s own accessKey and secretKey too, so the package’s default key never reaches the render. The connection record itself never reaches a render (ce daemon/services_seams_connections_mint.go, modules/connections/providers/s3hold/hold.go). Serving the held key logs X200464HLDUNSCOPED, naming the tenant, the app and the endpoint. SHC keeps a copy of what it served in rig’s vault for this app. An update never reads a held copy back: it asks the connection again, so a key rotated in b2 reaches the app on its next update (SHC-1457).
  2. It renders Nextcloud’s compose with SHC_S3_HOST, SHC_S3_BUCKET, the key pair and SHC_S3_SSL set.
  3. It runs the Postgres socket’s job, which creates the database and the user. The connection runs no job: nothing checks the bucket before Nextcloud starts, so a missing bucket or a key B2 rejects shows up in Nextcloud’s own log on its first write. The external-s3 front runs that check first, if you want the install refused instead.
  4. It starts Nextcloud, which keeps its files in the bucket from its first start. Every start renders the bucket, endpoint and key into Nextcloud’s objectstore config in config/zz-shc.config.php (apps/flagship/nextcloud/compose.yaml, SHC-3439).
Terminal window
$ shc uninstall cloud -t rig -y

Uninstalling Nextcloud leaves the bucket and every object in it, and leaves pg’s database and user, as in step 4. For the s3 edge SHC drops its own copy of the key; the key stays in the connection and at B2. To drop the files, empty the bucket at B2.

Keep cloud and pg installed for the next step.

Next: Step 6: Nextcloud add-ons.