Skip to content
SHC Docs

Connections

A connection holds the credentials for something outside SHC: a DNS provider, a cloud account, an object store. SHC keeps the secret in the vault and never writes it into a file an app can read. The S3 server from the Nextcloud page, store, is the provider here. Publish its port so the node can reach it, and make a bucket in it.

home01
$ shc update store --expose 9000=versitygw:9000
updating deployment "store"
...
$ shc exec -s store -S versitygw -- mkdir /data/learn

A connection’s coordinates are typed inline. Its secrets are not: the command line is kept by the shell’s history and the process list, so a secret typed there is refused. The key pair goes in a file that --value-file names, a JSON object of the secret fields; --cred secret_key=- --value-file <path> reads one field from a file that holds only that value.

~/learn/gateway.json
{"access_key": "learn", "secret_key": "P@ssw0rd"}
home01
$ shc connection connect gateway --type s3 --cred s3_endpoint=localhost --cred port=9000 --cred region=us-east-1 --cred use_ssl=false --cred probe_bucket=learn --value-file ~/learn/gateway.json
...
$ shc connection ls
NAME TYPE TENANT SCOPE DNS PURPOSE LOCATION
gateway s3 prod tenant - - -
$ shc connection show gateway
...

SHC checked the key against the endpoint before it stored it, listing the bucket named by probe_bucket. shc connection show prints the coordinates and reports each secret as set, never its value. localhost is where the node reaches the published port. Inside a container localhost is the container itself, so a connection an app consumes names an s3_endpoint the app can reach: the gateway’s own name on the deployment network, or a host on the LAN.

A connection serves nobody until it is granted to a tenant. An S3 connection holds one key for the whole endpoint, so the grant says so.

home01
$ shc connection grant gateway --capability s3 --grantee prod --boundary '{"unscoped":true}' --tenant prod
...
$ shc connection grants --tenant prod
CONNECTION TENANT CAPABILITY GRANTEE BOUNDARY
gateway prod s3 prod true

external-s3 is a headless app that serves the s3 socket from a bound connection and runs nothing: a front, a deployment that stands in for the connection. -C binds the connection the app declares.

home01
$ shc install external-s3 -s objects -C s3=gateway --var s3.bucket=learn
installing deployment "objects"
✔ installed deployment "objects"

Once the daemon has read it, shc ls gives objects the status external: a front runs no container of its own.

home01
$ shc ls
STACK TENANT ENV APP STATUS NODE
cloud prod prod nextcloud running home01
db prod prod postgres running home01
objects prod prod external-s3 external home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01
db prod staging postgres running home01

An app that has an s3 plug binds the front with -i s3=objects, or the connection itself with -i s3=@gateway, and gets the key pair through the socket. Both need the grant.

A connection can belong to the platform instead of a tenant. --scope system with -t master stores one every tenant can be granted.

home01
$ shc connection connect shared --type s3 -t master --scope system --cred s3_endpoint=localhost --cred port=9000 --cred region=us-east-1 --cred use_ssl=false --cred probe_bucket=learn --value-file ~/learn/gateway.json
...
$ shc connection ls -t master
NAME TYPE TENANT SCOPE DNS PURPOSE LOCATION
shared s3 master system - - -

A brand is a logo bundle an app with a branding plug resolves by name, so one tenant’s apps can carry its mark. The bundle is an SVG or a PNG under one megabyte, and it is kept in an S3 connection the master tenant can read, which shared now is. The Pro licence manages the brand named default; a brand with a name of its own, one per tenant, is the Enterprise white_label entitlement.

~/learn/logo.svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><circle cx="32" cy="32" r="30" fill="#1f6feb"/></svg>
home01
$ shc branding set default --logo ~/learn/logo.svg
...
$ shc branding list
...
$ shc branding delete default --yes
...
$ shc connection rm shared -t master --yes
...

Take the pieces apart in reverse: the front, the grant, the connection.

home01
$ shc uninstall objects --yes
uninstalling deployment "objects"
[objects] Complete 4/4
✔ remove from home01
✔ take the safety backup
✔ leave every node's service VIP table
✔ tear down
✔ uninstalled deployment "objects"
$ shc connection revoke-grant gateway --capability s3 --grantee prod --tenant prod
...
$ shc connection grants
no grants in tenant "prod"
$ shc connection rm gateway --yes
✔ removed connection "gateway"
$ shc connection ls
no connections in tenant "prod"
$ shc update store --expose 9000!
updating deployment "store"
...

objects keeps nothing of its own: its bucket is the one the connection names. The uninstall still takes its safety backup first, and that backup holds nothing, because a bucket outside the node is not the node’s to archive. With the front gone nothing holds the connection’s credential, so shc connection rm takes the connection away.

shc connection and shc branding typed alone answer for the whole group.

home01
$ shc connection
...
$ shc branding
...

A DNS connection is made the same way, with --zone naming the zones it manages and --purpose saying whether they are public or private; the networking ladder connects one. The seven deployments are as the last page left them, store holds an empty bucket learn, and no connection remains.

Next: Storage providers.