Chapter 04

Getting your code on

On a catalog site there is no build pipeline: you put files in the folder, then restart the site. This chapter is short because the mechanism is — but the restart is not optional, and that part catches everyone.

A custom stack deploys the other way round — its source is always git, and the panel pulls, builds and starts it when you press Deploy. Nothing in this chapter applies to one.

The shape of a deploy

Whatever tooling you wrap around it, every deploy here is the same three steps.

1. Get the files into the site folder — on a static or single-page-app site that is /var/www/virtual/<your-domain>/ directly; on a Laravel site the app goes into that folder's application/ subdirectory (/var/www/virtual/<your-domain>/application/).
2. Do any work the app needs — install dependencies, run migrations, rebuild caches.
3. Restart the site from the panel, so PHP picks up the new code.

Step 3 is required for any change to PHP code — including Blade templates. The only things exempt are static assets: CSS, JavaScript, images and fonts are served straight off disk by the web server without PHP involved, so they update the moment you copy them up.

Step 1 — moving files

The platform gives you one way of its own: SFTP, opened with an SSH key you add to your account. Anything beyond that — a shell and rsync, a copy from somewhere else — depends on what access your operator has given you separately.

SFTP with your own key

Open Your account in the panel and pick the SSH keys tab. Paste the public half of an SSH key and every site you hold is reachable from any SFTP client. Every account gets this, administrator and site owner alike, and what a key reaches is decided by the account it sits on, never by the key itself.

If you have no key yet, make one and paste the file whose name ends in .pub:

$ ssh-keygen -t ed25519
$ cat ~/.ssh/id_ed25519.pub

The panel shows the host, the port and your username on the same page. The username is your email address, and the @ in it has to be quoted, or the client reads everything before it as the name of a machine:

$ sftp -P 2223 'you@example.com'@your-server

Without the quotes the error names a host that does not exist rather than the quoting, which is why it is worth getting right the first time. Cyberduck, WinSCP and FileZilla take the host, the port and the username in three separate fields, so the question never comes up there.

A key is the only way in. There is no password to offer and cannot be one; a client that tries is refused, and that is the design rather than something your operator has not finished setting up.

What you see when you connect

One directory per site you hold, and inside each one that site's folder. Not the server, and not a home directory with anything else in it. If you hold no sites the session is empty — that is not a fault, and the SSH keys page says so before you try.

The list is worked out fresh on every connection. A site handed to you appears the next time you connect, a site taken away is gone the next time you connect, and there is nothing to refresh, re-add or re-authorise. The panel's own site never appears, for anybody, administrators included.

Two things come up immediately:

• What you upload is owned correctly. A file put there over SFTP is exactly as usable by the site as one a deploy wrote. There is nothing to chown afterwards.
• A folder mounted from one of your other sites is not there. That arrangement lives inside the running container, and an SFTP session is looking at the folder on the server. Chapter 06 describes those mounts.

A session sees the directories listed for it and nothing else. That confinement is applied by the SFTP service; it is not a filesystem permission boundary underneath, which is worth knowing when you decide who gets an account.

A removal takes effect on the next connection rather than at once: a session already open is not interrupted, and handing a site to a different owner behaves the same way. The same public key can also sit on more than one account, each authenticating as itself, which is what you want if you hold both an administrator account and a personal one.

An administrator can see and remove the keys on any account, and cannot add one — a key is the account holder's own credential. Keys are shown in full on purpose: a public key is public, and being able to compare one against what somebody tells you they added is the whole point of showing it. If the SFTP service is not running on this box, the page says so rather than listing keys that would not work.

Where each kind of site's files go

On a static or single-page-app site you publish the built output to the site folder directly — the two behave identically here, including the caching of everything under assets/. On a Laravel site you publish into the folder's application/ subdirectory, and you keep two things outside it: <folder>/storage/ (the durable Laravel storage tree — logs, caches, uploaded files; the image scaffolds it for you) and <folder>/.env (your credentials, placed on the box). The deploy symlinks both back into application/, which is what makes it safe to wipe and re-publish application/ on every push:

# from your project, into application/ on the box
rsync -az --delete \
  --exclude .git --exclude storage --exclude .env \
  ./ user@box:/var/www/virtual/app.example.com/application/

# point storage/ and .env at the durable copies beside application/
ln -sfn ../storage /var/www/virtual/app.example.com/application/storage
ln -sfn ../.env    /var/www/virtual/app.example.com/application/.env

Excluding .env and storage from the sync matters: they are the two things that must not be overwritten — .env holds your credentials and lives only on the box, and storage/ holds logs, caches and uploaded files you would otherwise wipe on every deploy. Because they sit outside application/ and are symlinked in, the --delete can never reach them.

Run php artisan storage:link once inside application/ so public/storage points at the storage tree. Vendor dependencies (vendor/, node_modules/) either travel in the sync or, more usually, are installed on the box in the next step.

Step 2 — work that runs inside the container

The PHP image ships Composer, git and the PHP CLI, so dependency installs and framework commands run inside your own container, against the mounted folder. Run them from the app root, /var/www/virtual/<your-domain>/application. Because the folder is at the same path inside and out, the commands read exactly as they would locally:

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache

Running these needs a shell in your container, which your operator grants. If you do not have that access, dependencies have to be vendored — committed or built elsewhere and synced up with everything else.

Step 3 — the restart

Use the restart action on your site in the panel. It clears the opcache by replacing the process, and it is also when newly added background programs are picked up.

A restart takes a few seconds and does not touch your folder, your domain, your certificate, or your settings.

Restart is the right button here. Its neighbour, Recreate, replaces the container with a fresh one from the image — harmless, but slower and not what deployed code needs. Chapter 02.1 draws the line between them.

Verifying

Load a real page in a browser. As covered in chapter 02, the status dot in the panel goes green as soon as nginx answers, and knows nothing about whether your application actually runs — a site with a fatal error still reports up.

If something is wrong, your logs are on the container's standard output: PHP errors, nginx errors, and anything your background programs print. Retrieving them means docker logs on the box, so ask your operator if you do not have that access.