Five repositories in one environment
This page is one worked example from an empty environment to five serving applications. It shows the normal path — the one most clients take — and the two advanced choices that go with it: two applications deliberately sharing one logical database, and a repository file switched to a hand-edited one.
The five applications come from five repositories, and each repository owns its own build, run commands, processes and environment references. Nobody copies a sibling application to change one of them.
| Repository | Runtime | Owns | Reads | Serves |
|---|---|---|---|---|
storefront | Node 26 | — | catalog database, the bucket | shop.example.com |
checkout | Python 3.15 | — | catalog database (granted), the payment key | checkout.example.com |
portal | Laravel 8.5 | portal database | its queue worker's own bindings | portal.example.com |
reports | Go 1.27 | analytics database | — | reports.example.com |
admin | Rust 1.99 | admin database | — | admin.example.com |
All five share the environment's capacity and services: read what sharing means before you choose this shape.
Before you start
Use a company-authorized account with permission to manage configuration and secret values. Each command enforces its own capability; read access is not permission to change a resource. Every example below uses the company slug and the identifiers your own installation returned, and none of them is a real credential.
| Placeholder | Where it comes from |
|---|---|
<company-slug> | Your company's slug in Hosting, which every company-scoped command names |
<environment-uuid> | The environment create answer, or hostingctl environments --company <company-slug> |
<application-uuid> | hostingctl application list <environment-uuid> --company <company-slug> |
<bucket-uuid> | hostingctl storage list --company <company-slug> |
<repository-selection-uuid> | hostingctl repository select …, or the Source screen |
<release-uuid>, <database-uuid> | The build answer, and hostingctl environment databases <environment-uuid> |
Sign in once; the session then carries every command below:
hostingctl login
Writes need --confirm, and --dry-run describes the same change without sending it. A refused write
exits 1 with the API's own reason, so a script can tell a refusal from a syntax mistake.
Download the complete documents
Take environment.yaml for the initial
environment review. Take each application's file and save it as hosting.yaml in its own repository:
storefront,
checkout,
portal,
reports and
admin.
These contain the full declarations, not just the excerpts below, and no credentials or platform UUIDs.
1. Create the environment
One environment, funded by the package the company already bought:
hostingctl environment create --company <company-slug> --name production --package empty_environment --confirm
Keep the environment UUID it answers with. Everything below is inside this one environment; nothing here creates a second one.
2. Add the one PostgreSQL server
The server is a service, not part of a configuration document: four logical databases sit on one server, and the server's process overhead is paid once for all five.
hostingctl environment service-add-review <environment-uuid> postgres --company <company-slug> --name shared-postgres
hostingctl environment service-add <environment-uuid> postgres --company <company-slug> --name shared-postgres --confirm
The name matters: each database declaration names server: shared-postgres, so the server a document
binds to is the one you actually added. A declaration naming a server the environment does not run is
refused by name rather than delivered to whichever server happened to exist.
3. Fund and bind one bucket
The bucket is a company purchase, funded from the package's included storage instead of a new
allocation. subscription assigns included storage in whole GiB; nothing here buys extra capacity.
hostingctl storage add --company <company-slug> --name production-assets --mode native --confirm
hostingctl storage subscription <bucket-uuid> --company <company-slug> --size 5 --confirm
hostingctl storage bind <bucket-uuid> --company <company-slug> --environment <environment-uuid> --native --confirm
One bucket is bound to this environment. A document that references platform storage needs exactly one ready, bound, funded bucket — purchased or package-assigned capacity both count — and is refused by variable name when that is not true, so nothing here depends on an operator rearranging storage later. The access key and secret arrive in each application's own Secret; they are never written into the document, the preview or a shell history.
4. Review and apply the environment baseline
The environment's configuration is one document. It declares all five members and every shared definition, and it is reviewed once by the person who owns the environment. The shared half is small:
version: "1.18"
databases:
catalog:
engine: postgres
server: shared-postgres
bindings: [storefront, checkout]
analytics:
engine: postgres
server: shared-postgres
application: reports
secrets:
internal_api_token:
description: Shared token the storefront and checkout present to each other
required: true
generate: {format: base64url, bytes: 32}
app_key:
description: Laravel application encryption key
required: true
generate: {format: laravel-app-key}
app_secret:
description: Internal admin signing and encryption key
required: true
generate: {format: alphanumeric}
payments_api_key:
description: Provider-issued payment key; Hosting never generates this one
required: true
catalog has two consumers, and each other database has one. An application consumes one database in
this version, so the shared database is how two applications read the same identity and credential; the
rest of the document adds portal and admin with their own databases and settings. Each member is a
complete declaration; the shapes for all five runtimes, with their build and run commands, are on
Application types, so this page can stay about the journey rather than about
five YAML files.
Internal secrets and provider keys are different things
generate is for an internal secret nobody issues — a token between two of your own applications, a
Laravel APP_KEY, a framework signing key. The formats in the example are the whole supported set, and
each states its own measure:
| Format | Measure | Default | Allowed |
|---|---|---|---|
base64url | random bytes | 32 | 16–256 |
hex | random bytes | 32 | 16–256 |
alphanumeric | output characters | 43 | 22–256 |
laravel-app-key | none — fixed at 32 random bytes | — | takes neither size field |
A provider-issued credential — a payment key, a vendor API token, a connection URL — has its own meaning
and therefore carries no generate declaration: Hosting never guesses what a slot meant and never
generates one. Leave it declared without generate and write its value separately, as step 4c does.
4a. Preview
hostingctl environment configuration preview <environment-uuid> --company <company-slug> --file environment.yaml
Preview writes nothing, buys nothing and generates nothing. It names each declared secret that has no
value yet, and says separately which of those will be generated when you apply and which you still have
to supply. That is the whole purpose of the step: you learn that payments_api_key is missing before
anything is applied.
4b. Save the reviewed draft
hostingctl environment configuration save <environment-uuid> --company <company-slug> --file environment.yaml --confirm
A draft records the document without applying it. It is what makes the declarations exist, so the one value you must supply has a slot to go into.
4c. Supply the provider key
hostingctl environment secret write <environment-uuid> --company <company-slug> \
--key payments_api_key --value-source file --value-file ./payments-key.txt --confirm
A value is never taken from an argument. --value-source file --value-file … reads a private file;
--value-source stdin reads standard input. Neither prints the value back.
4d. Apply
hostingctl environment configuration apply <environment-uuid> --company <company-slug> --file environment.yaml --confirm
Applying generates the four unset internal secrets exactly once, in the same transaction that records the revision, and queues the environment's normal reconciliation. Three rules decide what happens to a slot that already holds a value, and all three are why applying twice is safe:
- an existing version wins, including when you change that slot's
generatesettings — re-applying the document never re-rolls a secret your applications already read; - only a genuinely unset slot is generated; a retried or concurrent apply cannot replace one that is already recorded;
- a recorded value that cannot be read is refused rather than regenerated, because a new value under the same name is a credential your application no longer expects.
Rotation is a separate, explicit write — see rotating a secret.
5. Each repository's own file
From here, a repository's hosting.yaml declares only its own application. The rule is strict, and it is
what keeps five repositories from overwriting each other:
An application-scoped document declares
version, the target application underapplications, and optionally a database that application owns. Shared definitions and sibling members are not permitted in it.
This is the reports repository's file, which also carries its own database:
version: "1.18"
applications:
reports:
runtime: go
runtimeVersion: "1.27"
source:
root: .
build:
install: [go, mod, download]
command: [go, build, -trimpath, -ldflags=-s, -o, bin/server, .]
run:
command: [./bin/server]
port: 8091
healthPath: /health
env:
DATABASE_URL: {database: analytics, field: url}
FEED_TOKEN: {secret: reporting_feed_token}
PORT: "8091"
databases:
analytics:
engine: postgres
server: shared-postgres
application: reports
Four things this shape means:
- It replaces that member. The fragment is the application's complete declaration, so a block you leave out of it is gone from that application. That is different from a sibling, which you cannot reach from here at all.
- A database is optional and must be the target's.
analyticsnamesreportsas its owner and grants nobody else. A database owned by another application, or one granted to a second consumer, is refused here and belongs in a full-environment review. - Shared definitions are referenced, never restated.
reporting_feed_tokenandanalyticsare declared once in the baseline; the fragment names them. - Omission is not deletion. Omitting a sibling, a database or a secret from the fragment removes nothing. Removing something is the separate, reviewed removal path in Applications.
6. Change one application
Every change to one repository follows the same two commands, and touches only its own member:
hostingctl environment configuration preview <environment-uuid> --company <company-slug> \
--file hosting.yaml --scope application --application-key checkout
hostingctl environment configuration apply <environment-uuid> --company <company-slug> \
--file hosting.yaml --scope application --application-key checkout --confirm
--scope defaults to environment, and application scope is never inferred from how many applications a
document contains: you name the target with --application-key. The server composes your fragment with
the environment's current baseline under the existing lock, so the other four members and the shared
definitions stay exactly as they were, and the preview shows the combined result.
Two refusals are worth knowing in advance, because both are about not surprising you:
- An incomplete baseline is refused. Application scope needs a complete, reviewed environment document first — the one you applied in step 4. It does not invent shared declarations from partial history.
- A pending sibling draft is refused. If someone else has a draft that differs from what is applied, an application-scoped apply stops and tells you to resolve it through full-environment review. Your change never silently applies, or discards, someone else's intent.
The format version is not yours to change here either: an application fragment uses the version the environment already records. Moving to a newer version is a full-environment review.
When the document came from a repository
If an application's configuration was imported from a repository, the review is bound to the exact bytes the platform fetched at that commit. Two consequences:
- Editing the imported text and submitting it is not the same document. The platform refuses the edited copy and asks you to import the repository again — it will not attest repository provenance for bytes the repository never served.
- A hand-edited document is a different source. To deliberately move that member onto a document you maintain yourself, confirm the switch once:
hostingctl environment configuration apply <environment-uuid> --company <company-slug> \
--file hosting.yaml --scope application --application-key admin --switch-mode --confirm
The switch is explicit because it changes who owns that member's composition: from then on, the file you submit is the source of truth for it, and a later repository import is the reverse switch.
7. Build and deploy that one application
Configuration is not a release. Applying records what the application should be; building and deploying put it on the host:
hostingctl application build <environment-uuid> <application-uuid> --company <company-slug> \
--source <repository-selection-uuid> --confirm
hostingctl application deployment <environment-uuid> <application-uuid> --company <company-slug>
hostingctl application deploy <environment-uuid> <application-uuid> <release-uuid> --company <company-slug> --confirm
application deployment is the read that distinguishes a queued build from a failed one and names the
release to deploy; the build's own log is hostingctl application build-log. A sibling needs no rebuild
because this application changed: it keeps its own release, and only a shared dependency it actually
consumes forces it to be rebuilt.
Sharing one database deliberately
catalog is the advanced shape, and it is worth being exact about what it does:
databases:
catalog:
engine: postgres
server: shared-postgres
bindings: [storefront, checkout]
- Both applications receive the same database and the same credential. Their
envblocks reference the same fields, so nothing is copied between them. - Hosting creates no per-application SQL role on that database. Two applications reading one database are two consumers of one identity, not two identities on one schema.
- Both applications' tables must be coordinated by you. Hosting does not infer schema compatibility and does not make two migrations atomic; a release task that migrates one consumer while the other is serving is your ordering problem.
- Removing a grant stops delivery, not access. Narrowing
bindingsto[storefront]stops delivering that database's fields tocheckout, and the platform refuses the change until that application is stopped and the stop observed. The passwordcheckoutalready holds is not revoked by the change. - The server overhead is still paid once whether or not two applications share a logical database; a shared server is what saves the process, and sharing tables is not required to get that saving.
The baseline already grants both consumers; no additional binding write is needed. If you manage grants
with environment database bind instead, --bind replaces the entire consumer list. Supply every
intended application UUID, comma-separated, rather than only the application being added.
Rotating and reading a secret
Rotation is its own explicit write, never a side effect of a deploy or of re-applying a document:
hostingctl environment secret write <environment-uuid> --company <company-slug> \
--key internal_api_token --value-source generate --replace --confirm
--replace is the confirmation that a value already set may be replaced; without it the write is refused.
The declaration's generate settings decide the new value's format. Because internal_api_token is read
by both storefront and checkout, both must be rebuilt and redeployed before their running processes see
the new value — the write changes the stored secret, not a running container.
Revealing is a deliberate read, and it is in the panel rather than in ordinary command output: open
Hosting → Configuration, find the declared secret and choose Reveal <name>. The activity record
notes that a value was revealed, never the value.
A generated value is never printed by the write that created it, never appears in a preview, and never
appears in a configuration document. Local development has its own control for that,
hostingctl environment secret local, which writes each declaration's declared local value instead of
reading a stored one.
What this setup shares, and what it costs
One environment is a shared failure domain. Its applications run in one shared Pod, so replacing that Pod restarts them together; the PostgreSQL server and environment-wide controls are shared too. Bounded burst allows competition for spare capacity; it is not a promise that every application's peak fits at once. Choose a separate environment for an application that needs its own protection boundary. This setup does not promise independent availability.
Sharing a server is an allocation fact, not an invoice discount. One PostgreSQL server counts its CPU and memory once, each logical database counts its own storage, and the bucket's assignment is counted once from the same included storage. Those are reservations inside the package you already bought, so this setup fits that purchase — it does not credit the bill, generate a smaller invoice, or refund a process you stopped by consolidating. If the combined reservations do not fit, the apply is refused rather than silently resizing anything.
Taking this to production
Reuse the definitions, never the identifiers. A production environment is created in its own right, with its own server, its own bucket and its own secret values, and the same documents reviewed against it.
- Identifiers do not travel. The UUIDs on this page came from one environment and mean nothing in another; each target resolves its own, so there is nothing to copy and nothing that would be accepted if you tried.
- Secrets are re-issued, not copied. A generated secret belongs to the environment that generated it. Applying the same document to a new environment generates new values there; a provider key is written into that environment separately.
- A repository import is reviewed where it is imported. Each target environment names its own repository selection and commit; an import reviewed against one environment is not an approval for another.
Next
- What an application in your environment is: Applications.
- The build and run commands for each runtime: Application types.
- Every field in the document: Configuration.
- Reading a database without copying a credential: Databases.
- Buying and binding object storage: Storage.