Chapter 02
Two kinds of site
Everything the panel runs is a site. But a site comes in two kinds, and which one you pick decides where your code lives, how it gets deployed, and how a domain reaches it. Almost every later chapter has a "for a stack it works like this instead" note in it, so it is worth choosing deliberately.
the common caseOne container, from an image the box already built — a static file server, one tuned for single-page apps, PHP 8.3 for Laravel, or any other image an administrator has added.
You bring files. The runtime is given.
compose + gitA Docker Compose project, cloned from your git repository and built on the box. As many containers as your compose file declares.
You bring the whole runtime. The platform supplies the edge.
Which one you want
The honest rule: a catalog site is less work in every way, so take it unless something in your app makes it impossible.
- Take a catalog site if…
- Your app is a static build, a front-end bundle, or PHP/Laravel. It needs one process serving HTTP, plus perhaps a queue worker and a scheduler. MySQL and Redis are enough of a backing store. You want deploy-on-push without writing a Dockerfile.
- Take a custom stack if…
- Your app is not PHP. Or it needs its own database engine — Postgres, Mongo, Elasticsearch. Or it is several services that talk to each other. Or its runtime is baked into an image you build yourself.
Inside a stack you choose the base images, the versions, and the patching schedule. Nobody upgrades them for you, and there is no health check that understands your services the way the catalog images understand nginx and php-fpm. The compose file is yours to keep working.
Side by side
| Catalog site | Custom stack | |
|---|---|---|
| Identified by | Its domain — app.example.com |
A slug — my-app. A stack has no domain of its own. |
| What runs | Exactly one container, from the catalog image | Every service in your compose.yaml |
| Your files live at | /var/www/virtual/<domain> | /var/www/stacks/<slug>/application |
| Source | Anything that can put files in the folder — rsync, scp, or the runner | Always git. The panel clones over SSH with a deploy key it generates |
| Deploying | Copy files in, then restart. Optionally on every push, via the in-container runner (chapter 10) | Press Deploy in the panel: pull, validate, compose up --build. No push trigger |
| Domains | One primary domain plus aliases. Published and unpublished with a toggle | Any number of equal rows, each pointing a domain at one allocated port. A row exists ⇒ it is served |
| Host ports | None, ever | Allocated by the panel, bound where only the edge can reach them. An administrator can additionally open one on the server for traffic that is not a website — SSH into a Gitea stack, say |
| Reaching MySQL / Redis | By service name on the internal network | By the host aliases mysql.nimbus and redis.nimbus |
| Renaming | Change the domain | Not possible — the slug is baked into every container, volume and path. Delete and re-create |
What both kinds share
The parts of the platform that are not about how your code runs are tabs on the site's own page — Environment, Databases and Locking, in one row with General, Deployments and Backup. Which of the three you are offered depends on whether your site has an application behind it, not on which kind it is.
- Environment
- An editor for the site's
.envfile. For a Laravel site that is<folder>/.env; for a stack it is/var/www/stacks/<slug>/.env, symlinked into the clone socomposeandenv_file: .envboth find it. Only the path differs. A static site has no.env, so it has no Environment page. - Databases
- Provision a MySQL database and user, reset the password, drop it. The same for a Laravel site and a stack. A static site is offered none — nginx serving files has nothing that could open a connection. Chapter 06.
- Locking
- Put the site behind the IP allowlist, in whole or by URL path prefix. Every site has this, whatever it runs — a lock is a rule at the edge, not something in your folder. For a stack, one lock covers every one of its domains. Chapter 08.
That is not a gap — it is the whole of what a folder of files can be given. Its row of tabs simply has no Environment and no Databases in it, rather than offering pages whose every control would do nothing.
One tab belongs to catalog sites alone: Mounts, which lists folders from your other sites that this one can reach, and the sites that reach into it. As a site owner you can read it and not change it — an administrator arranges those. A stack has no such tab; it composes its own services from its repository. Chapter 06.
The edge is genuinely identical, though: both kinds sit behind Caddy, which terminates TLS and gets the certificate, and everything served over a domain arrives that way whichever kind you chose. Chapter 07. The one exception is a stack whose administrator has opened a port on the server for traffic that is not HTTP; that connection skips the edge entirely, and chapter 02.2 says what follows from it.
Read on
Pick the one you are building and read it. The rest of the guide — images, deploying, background work, services, domains, access — is written for catalog sites, with the differences for a stack called out where they exist.