Where your files live

Every site, app and volume that needs files on a server gets a folder there. This chapter says where the folders are, how they are named, which names you can choose, when a name stops being changeable, and what each action does to the files. For who owns the files and how a login reaches them, see Hosting Accounts and isolation.

The model

Each Hosting Account has one folder tree on every server where its services run:

/srv/users/alice/                 root owns it; the SFTP jail root
  home/                           alice's login home
  tmp/                            alice's private temporary folder
  production/                     one folder per environment (the scope)
    services/
      example.com/                one folder per service that needs files
        public/                   uploaded files for a site you fill over SFTP
        releases/<release id>/    sealed, read-only builds
        current                   link to the release that is live
        shared/                   files that must outlive a deploy
        logs/                     the app's own log files
    volumes/
      uploads/                    one folder per storage volume
  staging/
  common/                         shared by every environment (below)
    services/
    volumes/

• home/ and tmp/ belong to the owner. Everything else is a folder TurboPanel makes for you.
• A scope folder is named after the environment (production, staging), or is common for things shared across environments.
• A service folder is made only for services that run from files on the host: sites, uploaded-directory sites and native apps. A service that only runs a container from an image has no service folder; its data lives in volumes.
• A volume folder is the bind-mount source for a storage entry of kind Directory on a host path. It belongs to the owner, so you can fill it and empty it over SFTP, but you cannot delete the folder itself.
• Which parts you can write. You can write to home/, tmp/, public/, shared/, logs/ and inside each volume. Every folder above those is root's, so a Hosting Account cannot rename, replace or delete a service, volume or environment folder, only empty the writable parts inside it.
• Project names are not in paths. The project's name and short name never appear on the server.

Over SFTP with the jail on, the owner sees the same tree starting at /, and signs in to /home.

Name rules

A folder name is fixed by the time the folder exists, so TurboPanel checks it up front. The same rules are applied by the app, the API and the host.

Reserved names. An environment (or a scope name) cannot be called base, common, home, tmp, services or volumes (those are the owner's own folders), and a handful of other words are kept free so a future folder never needs a rename: data, sites, backup, backups, logs, cache, run, var, etc, bin, root, public, releases, current, shared, lost-found and tmp-staging.

Name from a domain. A website's folder name defaults to its domain, made safe for a folder:

1. Spaces and one trailing dot are dropped, and an international domain is turned into its xn-- form.
2. It is lowercased.
3. A leading *. becomes wildcard..
4. If the result is longer than 63 characters, it is cut to 54 characters, then - and eight characters of a fingerprint of the full domain are added, so the same domain always gives the same name.
5. If another service of the same owner in the same environment already has that name, -2, -3 and so on are added, up to -99.

A later domain change, an extra domain or an alias never renames the folder. A name you type yourself is never changed for you: if it is taken, the request is refused with directory_name_taken.

Choose how folders are named for your organization

An organization owner or manager picks how service and volume folders are named. The setting applies to every service and volume created afterwards.

Environment folders are always the environment's name. Over the API it is GET and PUT /api/client/v1/organizations/{id}/directory-defaults (names: slug, uuid or both). It can change until the first folder is made anywhere in the organization. After that it is locked, and changing it returns directory_names_locked.

Shared (common) folders

By default a service or volume belongs to one environment and lives under that environment's folder. To keep something across environments, create it as common when you add it. It then lives under common/ and is not tied to an environment name.

• The choice is made at creation and cannot change afterwards (scope_locked).
• Any environment of any project in the organization can use a common service or volume of the same Hosting Account. An environment lists the ones it uses, and POST /api/client/v1/environments/{id}/shares adds one (serviceId or storageId). Removing the share stops the environment using it and leaves the asset alone.
• Adding a share is refused with asset_not_common (the service or volume is not common), asset_in_this_environment (it belongs to this environment already) or asset_has_no_owner (it has no Hosting Account yet). Adding the same share twice is harmless.
• A common asset cannot be deleted while another environment uses it (common_asset_in_use).
• A common volume is mounted only by environments that use it, and only at the mounts they ask for.

Common folders never block an environment rename, because they do not contain the environment's name.

When a name is locked

Names that appear in a path stop changing once something exists on disk under them.

An environment's name is the folder name on disk, so it cannot be renamed while folders exist under it. The error lists up to 20 of the folders that block it, each with its server and a plain reason, for example being removed, waiting for server Beta to come back. Remove those services and volumes first, or keep the name. Moving an environment to another server is locked the same way, and an environment with folders cannot be deleted either (environment_has_folders) until they are removed.

What counts: a folder in the state planned, present, removing or orphan. What does not count: an empty environment folder with nothing in it, a service that has no folder (container-only), a managed database (it lives outside the owner's tree), and a folder marked missing. A rename also waits for a running deploy of the environment (environment_deploy_running).

What stop, delete and removing a service do

An empty environment folder is left in place when its last service goes. It costs nothing and does not lock any name.

Orphan folders

An orphan is a folder on a server that no service or volume owns any more: a service removed from the compose document (its files are kept on purpose), or a folder found on the server that the app did not make. The app raises an alert, lists the orphan with the reason no service or volume owns this folder on server X, and counts it toward the environment-name lock until an organization admin removes it or the service is added back. Nothing is deleted automatically.

The host also reports the folders it finds on its disk; any difference from what the app expects shows as an orphan (a folder only on disk) or missing (a folder the app expects that is not there), with an alert.

Volumes and the user a container runs as

A volume folder belongs to the Hosting Account. A container may run as any user and TurboPanel never refuses a compose document for that. When a service declares a numeric user other than root, that user is given access to the volume folder with a permission entry; the folder's owner is never changed to root or to the image's user, so you keep access over SFTP. For an image that must own its data as a fixed user, use a Docker named volume instead of a directory.

Backups and TurboPanel's own folders

Backups and the platform's own state live outside the owner's tree.

The path of a backup is stored relative to the backup folder (for example managed/<id>/<backup id>.dump), so moving the backup folder to another disk and pointing TURBOPANEL_BACKUP_DIR at it does not break restores. A volume restore stages its files inside the volume folder (.tp-restore-stage, .tp-restore-old and .tp-restore-done, all starting with a dot), so those names cannot clash with anything you create.

Errors

Related

• Hosting Accounts and isolation — who owns each folder and how SFTP is locked to it.
• Storage, variables and secrets — volumes, copies and backups.
• Writing compose — how a site is served from public/ or current.
• System users — the Hosting Account.