Create a new site and publish it on its domain

Before you start

A new site needs a target before its source can be uploaded. An owner can create one through MCP as a managed component, derived from a template: a target the operator has already configured on the same server with a build recipe, a registry destination and a deployment profile. A server without a suitable template has nothing to derive from; ask its operator to install one.

Managed components are available on servers whose agent supports them. A server with an older agent does not offer these operations until its operator upgrades the agent. All component operations are owner-only. Creating, removing and publishing also need the hostwatch:write scope, confirm:true and the server’s governance policy.

This path suits a site or stateless service that starts without secrets or stored data. A managed component never inherits the template’s environment file, secrets, data mounts, source files or domains. If the application needs any of those, the operator adds them to the agent configuration separately.

1. Preview the component

Call component_preview with an id of 3 to 40 lowercase letters, digits and hyphens, and the templateId. You can also set containerPort (1024 to 65535, default 3000), memoryMb and cpus up to the template’s limits, and healthPath (default /). You cannot supply a command, host path, image, registry or port mapping.

The preview returns what would be created: the registry destination renamed to the component id, a loopback port from a reserved range, the health URL, the limits, the lists of what is inherited and what is not, and a revision. Read every derived value before continuing.

execute { operation: "component_preview", nodeId: "SERVER_ID", args: { id: "docs-site", templateId: "web" } }

2. Create exactly what you previewed

Call component_create with the same fields and the preview’s revision as expectedRevision. If the request or the server changed in between, the call is refused and you preview again.

Creation makes empty private source directories and records the component. Nothing is built, published, started or exposed. The component then appears in components and can be addressed by its id like any other target.

3. Build and deploy the first version

A new component has no previous image, so its first build must use full mode with a complete source archive. source_preview reports the unbuilt marker as the source digest; pass it back as expectedDigest to source_build. Archive rules and upload handling are the same as in the guide to updating a component.

Publish the built image with image_publish_preview and image_publish, because the registry tag does not exist yet. Then read deployment_preview and call deployment_create with expectedRevision set to absent. Later releases can use partial or full mode. At this point the site answers on its loopback port only.

4. Publish it in three stages

component_ingress publishes the component through the server’s shared Nginx. Each stage is previewed with component_ingress_preview and applied with the returned revision. The preview shows the exact Nginx file, the DNS check for each domain, the certificate status and any blockers.

Every Nginx write is tested with the whole configuration. If the test or the reload fails, the previous file is restored. Hostwatch does not edit DNS: you change the A and AAAA records at your DNS provider and choose when to cut over.

1. Stage http: a proxy to the component and the certificate challenge path, for 1 to 4 domains that no other site on the server serves. DNS can still point elsewhere, so you can test before any visitor arrives.
2. Point every A and AAAA record for those domains at this server, and remove records that point anywhere else.
3. Stage certificate: starts certificate issuance once every domain resolves only to this server. It runs in the background.
4. Stage https: when a current certificate covers every domain, port 80 redirects and port 443 serves the site over TLS.

Check each stage and the certificate

Poll component_ingress_status. It returns the DNS check, the certificate’s names and expiry date, and the last issuance result: issued, or failed with the last lines of the certificate client’s output. Correct the cause of a failure before starting the stage again; repeated failed attempts can be rate limited by the certificate authority.

Verify from outside the server as well. After https, request the site with certificate verification on, compare the certificate’s names and expiry with the status, confirm that plain HTTP redirects, and finish with one representative request to the application. The certificate is renewed afterwards by the server’s own renewal timer.

Take a site down or remove the component

The remove stage of component_ingress deletes the managed Nginx file with the same test and restore as the other stages. The certificate stays on the server.

component_remove forgets a managed component that has no container and no ingress, so remove the ingress and delete the deployment first. Built images, registry tags and source releases stay for retention, and no application data is touched. A target that the operator configured cannot be removed this way.