Multi-host projects
A project can serve more than one name. An app, its WebSocket server and its file store can each answer at a host of their own, all from one project in Nearhost.
Several web routes
Section titled “Several web routes”A project can have several web routes. The first is the primary: it is served at the project’s main name, and at any hosts you give it too. Every other web route is served only at its own hosts, so it needs at least one.
You give a route hosts in three ways:
- In the interface. On the routes step of the add or edit form, choose a web route and press
h. Type its hosts separated by spaces, and pressenter. - On the command line.
nearhost add --host <host>adds a host to the primary web route. Repeat it for more. - In the project’s files. A
.nearhostrclists hosts for each route, and presets can find them in.env. See Hosts from presets.
In the routes view on the main screen, w makes a route web. If it has no hosts, it becomes the primary. Other web routes with no hosts become ignore, so a route with hosts of its own keeps serving them.
Host patterns
Section titled “Host patterns”A host is an exact name, such as api.local.example.com, or a pattern with * in place of one label, such as *.status.local.example.com.
*stands for exactly one label.*.status.local.example.commatcheseu.status.local.example.com, but notstatus.local.example.comora.eu.status.local.example.com.*can be the leftmost label or one in the middle, as ininternal.*.local.example.com.- The part to the right of the last
*must be at least two labels, and more than a public suffix. A pattern that is only wildcards is refused, and so are*.test,*.comand*.co.uk.*.myapp.testis allowed. localhostis allowed as an exact host. Any other name needs at least two labels, and an IP address is refused.nearhost.localhostis refused withnearhost.localhost is Nearhost's own page, since Nearhost’s page is served there.- Hosts are lowercase.
Which route answers
Section titled “Which route answers”When several hosts match a name, the most specific one answers:
- An exact host beats any pattern.
- Among patterns, the one with more fixed labels wins, so
internal.*.local.example.combeats*.*.local.example.com. - Patterns with as many fixed labels are taken in lexical order.
A host can be served by only one enabled project. Two exact hosts clash when they are the same name, and two patterns when they are written the same. An exact host under another project’s pattern does not clash, because the exact host wins. Saving an enabled project, or starting one, that would serve a host another enabled project serves is refused with host <host> is already served by project "<other>". nearhost doctor warns, as hosts.overlap, when a pattern overlaps another project’s without being the same.
Certificates and DNS
Section titled “Certificates and DNS”Each exact host gets its own certificate. A name under a pattern gets one the first time it is visited. See TLS and the proxy.
An exact host goes in the hosts file while its project is enabled. One that does not end in .test is left out when DNS already points it only at loopback addresses, and localhost is never added. Patterns never go in the hosts file, because the file cannot hold them, so a pattern’s names need DNS that points them at this machine. nearhost doctor reports a pattern that does not resolve here as hosts.unresolved-pattern. See The hosts file.
What needs approval
Section titled “What needs approval”A host that does not end in .test, any pattern and localhost wait for your approval before they are served. A host you type with --host or h is approved by typing it. See Approval.
Hosts from presets
Section titled “Hosts from presets”A preset can name hosts as well as ports. The nearhost/sail preset reads them from .env:
| Variable | Served on the port in |
|---|---|
APP_URL |
APP_PORT, or 80 |
REVERB_HOST |
FORWARD_REVERB_PORT, or 8080 |
FILES_URL, MINIO_URL, or both |
FORWARD_MINIO_PORT, or 9000 |
Only the host is taken from each value. A port in the URL is ignored, and the route’s port comes from the variable beside it. The Reverb and MinIO hosts are read only when their port variable is set in .env or named in the Compose file.
- Inference never proposes
localhost, an IP address or a name without a dot. A malformed name is left out with a warning, and so isnearhost.localhost, asnearhost.localhost is Nearhost's own page, so it is left out. - A route that has inferred hosts becomes a web route. A
loopbackroute cannot have hosts, so they are dropped with a warning. - A
.nearhostrcthat lists a route wins over the hosts presets found for it. See Keys. nearhost addleaves out an inferred host that another enabled project already serves, with a note:Not serving <host>: project "<other>" already serves it.A later web route left with no hosts becomesignore. A project added with--disabledkeeps them, since it serves nothing yet. The interface does not leave them out: it refuses to save, and you remove the host withh.
Inferred hosts are fixed when the project is added or edited. Changing APP_URL later does not change what is served. Editing the project, with e in the interface, adds any newly inferred hosts to a saved web route and never removes a saved one. nearhost doctor reports a host the project’s settings name that no web route serves, as routes.unserved-host, and tells you to edit the project.
Where the URLs show
Section titled “Where the URLs show”The project view in the interface lists every URL under the project’s name. A pattern is shown dim, since a browser cannot open it. For a coding agent, /nearhost status reports the main URL as url, and every URL the project serves, the main one first, as urls. See Add a project from an agent.
An example
Section titled “An example”A Sail project with an app, Reverb and MinIO, whose Compose file publishes APP_PORT, FORWARD_REVERB_PORT and FORWARD_MINIO_PORT, has this in its .env:
APP_URL=https://shop.local.example.comAPP_PORT=8010REVERB_HOST=ws.shop.local.example.comFORWARD_REVERB_PORT=8090FILES_URL=https://files.shop.local.example.com:9010FORWARD_MINIO_PORT=9010With nearhost/sail enabled, nearhost add asks you to approve the three hosts, since none ends in .test. Nearhost then serves:
| URL | Port |
|---|---|
https://shop.test |
8010 |
https://shop.local.example.com |
8010 |
https://ws.shop.local.example.com |
8090 |
https://files.shop.local.example.com |
9010 |
shop.test is the main name, so it is served on the primary route with the app’s own host. Add the project with --alias shop.local.example.com to make the real name the main one.