Skip to main content

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.

RepositoryRuntimeOwnsReadsServes
storefrontNode 26—catalog database, the bucketshop.example.com
checkoutPython 3.15—catalog database (granted), the payment keycheckout.example.com
portalLaravel 8.5portal databaseits queue worker's own bindingsportal.example.com
reportsGo 1.27analytics database—reports.example.com
adminRust 1.99admin 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.

PlaceholderWhere 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:

FormatMeasureDefaultAllowed
base64urlrandom bytes3216–256
hexrandom bytes3216–256
alphanumericoutput characters4322–256
laravel-app-keynone — 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 generate settings — 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 under applications, 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. analytics names reports as 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_token and analytics are 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 env blocks 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 bindings to [storefront] stops delivering that database's fields to checkout, and the platform refuses the change until that application is stopped and the stop observed. The password checkout already 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​