TOADSource ↗

From an OpenStack project to a verified platform

Put your first website online.

Start manually with one inexpensive cloud node and an ordinary HTML website. Learn what every layer does, then keep the same operating model when the site becomes an application or the platform grows.

The first journey

Manual first. Agents when you want acceleration.

The first walkthrough asks you to type the commands, inspect the plan, edit the website, and verify the result. Once that model is clear, an agent can operate the same declarations and checkpoints for you.

Before you begin

01

Cloud project

An Infomaniak Public Cloud project and a dedicated service user—not a personal password.

02

Demo address

Use the provided demo.toad.remigirard.dev address. No domain purchase is needed for the demo.

03

Operator

Choose Docker for the fewest local tools, or run the source directly when you want to inspect every dependency.

Choose how TOAD runs

One workflow, two transparent operator paths.

Docker-only

Recommended for the shortest setup. Docker Compose runs the reviewed operator with its filesystem read-only, no added capabilities, and private persistent state.

Source checkout

Best for learning and contributing. You install Node.js and pnpm, then inspect the TypeScript, locked OpenStack tools, and Ansible playbooks locally.

Both paths execute the same TypeScript commands, declarations, approval points, and verification checks. Repository or package access is required while the project remains in private preview.

Docker-only · recommended

Download the signed release, then keep state between commands.

gh release download --repo RemiGirardDev/TOAD-infra   --pattern 'toad-compose.yaml*'
sha256sum --check toad-compose.yaml.sha256
mv toad-compose.yaml compose.yaml
mkdir -p .toad/state/home .toad/backups
gh auth refresh --hostname github.com --scopes read:packages
gh auth token | docker login ghcr.io   --username YOUR_GITHUB_USERNAME --password-stdin
docker compose run --rm --volume "/protected/clouds.yaml:/input/clouds.yaml:ro"   toad demo --clouds /input/clouds.yaml --plan

The release Compose definition pins the signed operator image by immutable digest and gives people and agents the same protected mounts and container restrictions. During private preview, GitHub CLI and the registry use the invited account without printing its token.

Source checkout · learn every layer

Check the workstation before creating anything.

git clone https://github.com/RemiGirardDev/TOAD-infra.git
cd TOAD-infra/openstackV3
pnpm install --frozen-lockfile
pnpm run check
cp /protected/location/clouds.yaml credentials/clouds.yaml
pnpm run doctor -- --json

Place clouds.yaml in the protected credentials directory yourself. The doctor explains missing prerequisites without asking you to paste a password.

Create the platform

See the cost, read the plan, then approve one node.

docker compose run --rm toad cost
docker compose run --rm toad demo --reuse --plan
docker compose run --rm toad demo --reuse
docker compose run --rm toad verify toad-demo --json

The cost command and plan create nothing. They show the dated rate assumptions, itemized estimate, VAT boundary, exact machine, image, network, services, and cost-bearing resources before asking for approval. The estimate is not live usage or an invoice. The source path offers the same commands through pnpm run.

Publish the first website

Create or import, preview, then publish. No registry required.

docker compose run --rm toad site create my-site
# Edit .toad/state/contexts/toad-demo/apps/my-site/site/
docker compose run --rm --service-ports toad site preview my-site
docker compose run --rm toad site plan my-site
docker compose run --rm toad site deploy my-site

Already have a small static build? Mount its output read-only and run toad site import. TOAD validates the files, packages them as immutable Swarm configuration, deploys through a pinned Nginx runtime, and verifies the HTTPS address.

The website is online · now open the hood

Follow one request through every layer.

docker compose run --rm toad site explain my-site
  1. Public nameThe readable address in the browser.
  2. DNSTranslates that name into a public IP.
  3. Public IPThe stable OpenStack address receiving the connection.
  4. FirewallAllows web traffic and keeps service ports private.
  5. TraefikTerminates HTTPS and selects the declared route.
  6. WebsiteA Swarm replica serves the immutable files.

Heat stack

The declaration that owns the machine, network, router, IP and firewall rules.

Server

A Linux virtual machine. The single profile creates one; production uses three managers.

Private network

The subnet where servers and services communicate without exposing container ports.

Ansible

Configures the operating system and Docker after Heat creates the cloud resources.

Docker Swarm

Keeps the requested number of service replicas running and coordinates updates.

Traefik

The public application entry point, HTTPS certificate manager and reverse proxy.

Swarm configs

Content-addressed website files. A changed file becomes an immutable update.

Monitoring

Prometheus measures, Grafana presents, and Alertmanager reports platform health.

mTLS

The browser certificate protecting administrative interfaces without a shared password.

Inspect the real resources

Connect each explanation to live evidence.

docker compose run --rm toad status
docker compose run --rm toad os stack resource list toad-demo
docker compose run --rm toad os server list
docker compose run --rm toad os floating ip list
docker compose run --rm toad os network list
docker compose run --rm toad app diagnose my-site --json
docker compose run --rm toad verify toad-demo --json

Read these one at a time: the Heat stack owns the cloud resources, the floating IP is the public network address, the server runs Docker, and the diagnosis proves the replica and HTTPS endpoint.

Then understand scaling

One contract, two platform shapes.

Single

One manager and one failure domain. It is inexpensive, understandable, and appropriate for learning or small services.

Production

Three managers retain control-plane quorum after one manager loss. Optional private workers add application capacity.

The website files, routing contract, deployment command and diagnosis remain the same when the topology grows.

Understand, then accelerate

The same checkpoints work with an agent.

Checkpoint
Manual learningYou type. TOAD explains.
Agent-assistedYou decide. The agent operates.
Understand

Read the architecture and identify what Heat, Ansible, Swarm, and Traefik each own.

The agent reads the operating contract and explains the same ownership boundaries before acting.

Prepare

Create the cloud user, place clouds.yaml, and run every local prerequisite check yourself.

Provide the protected credential file; the agent diagnoses readiness without asking you to paste secrets.

Plan

Inspect the Heat environment, chosen image, network, service shape, and expected cost line by line.

Receive a compact plan with the exact stack, resources, changes, cost, and stop points.

Deploy

Type the declarative command and follow Heat, host configuration, Swarm, ingress, and monitoring.

Approve the displayed plan once; the agent reconciles the same declared files and narrates progress.

Prove

Read the verifier output and account for each node, replica, certificate, endpoint, and boundary.

Get the same machine-readable evidence summarized with failures, limits, and the smallest next action.

Same declared state · same safety checks · same acceptance evidence

Later · server applications

Move to the launcher when the website needs a runtime.

# Public image
pnpm run launch -- /path/to/my-app --plan

# Or keep the image private
pnpm run registry -- login registry.example --username USER
pnpm run launch -- /path/to/my-app --plan --private   --image registry.example/account/my-app

The application launcher is the next lesson for APIs, Node servers, and framework runtimes. It adds an immutable container image while keeping the same plan, approval, policy, and diagnosis. Private credentials stay in the selected client context and reach the Swarm manager only for the authenticated deployment.