Publishing services

What it is

You run a service at home, say a document server on your NAS, and want to open it from any browser as docs.example.org. Your router at home opens no port for this, and its address is in no public record.

A few words first:

• A domain is a name you own on the internet, such as example.org.
• A DNS record is an entry at your DNS provider that says which address a name points to.
• TLS is the encryption a browser uses for https:// addresses.
• A certificate proves to the browser that the server really is docs.example.org. juist gets one from Let’s Encrypt.
• An ingress is a device of your network with a public address, a small VPS for example, that an admin gave the role ingress. It takes connections on port 443, reads the name the browser asks for, and passes the connection through the tunnel to the member that publishes the name.

The ingress ends no TLS, so it never sees the content. TLS ends at the NAS, and the NAS passes the plain connection on to the service. One ingress serves every name of the network.

Setting it up

juist network domain example.org
juist grant vps ingress
juist publish add nas docs

juist ingress serve

juist publish serve docs=127.0.0.1:8080

juist grant and juist publish add name the next step and the device it runs on. Run there by that device’s operator, they take that step too. juist invite vps --ingress admits a new device as the ingress at once.

Keeping the server away from your network

A service member keeps the server away from them: a juistd of its own beside the service, with no privilege, which every device keeps from opening any connection to it. Only its replies pass. Run it beside the service, for instance in a container on the service’s network:

juistd --serve immich=immich-server:2283 --home /var/lib/juist
juist -s /var/lib/juist/daemon.sock join 'juist:…' --name immich

Then, on an admin’s device, juist grant immich service and juist publish add immich immich. It ends TLS itself, with a certificate from Let’s Encrypt, and answers nothing but what it publishes and log sync. It has no way out, so a service that downloads things at its first start needs that done beforehand.

Good to know

• A published name is one label under the domain: docs.example.org, not a.docs.example.org and not example.org. Publishing the domain itself is planned.
• Without =ADDR, as in juist publish serve, the service ends TLS itself and holds its own certificate, as it would facing the internet.
• juist publish add nas docs --proxy hands the service the client’s address in a PROXY protocol v2 header.
• Members that turned names on with juist names on reach a name published on 443 directly through the tunnel, with the same certificate (Names).
• juist publish lists the published names. juist publish remove nas docs stops publishing one. juist publish serve --stop and juist ingress serve --stop undo the two serve steps.
• An ingress runs on Linux, for now, and so does juist’s own TLS. A target on FreeBSD ends TLS in the service itself.
• An ingress is never a voucher or an exit node, and routes no subnet. Every member takes from it only connections to the ports it publishes and serves, and log sync. Everything else from it is dropped.
• The ingress runs as its own user, juist-ingress, holds no key of the network, and may ask juistd one thing: what is published.
• An ingress whose view of the network is stale serves nothing. If its juistd stops answering, the names go down within ten seconds.

If something goes wrong