Deploying the site

Deploying is building the site and uploading it to the server with a single command. You say where in sitio.yml; despliegue means “deployment”, destino the destination, servidor the server, usuario the user and ruta the path. This is for an FTP, which is what almost any shared hosting offers:

despliegue:
  destino: ftp
  servidor: ftp.example.com
  usuario: ana
  ruta: /public_html

The password does not go there, because sitio.yml is shared and versioned. It goes in .secretos.yml (“secrets”), which is not:

despliegue:
  clave: 'the-password'

And you upload in two steps: first see what it would do, then do it.

php ehundu.phar desplegar --simular
php ehundu.phar desplegar

What it uploads and what it deletes¶

desplegar builds the whole project, like compilar. If there are errors, it publishes nothing. If there are none, it compares what was built with what is already on the server and uploads only what is new or has changed. To know this, it leaves a file at the destination, .ehundu.json, with the list of what it has uploaded, each file with its MD5 and its size. Any machine that deploys the site sees the same thing, so you can publish from your laptop or from another computer.

What matters is what it does not do: it deletes only what it uploaded itself. What is on the server and not in that file is never touched, be it the file you verified a domain with, the .well-known of a certificate or a PHP form somebody left there. The flip side is that, the first time you deploy over a site that already existed, the files of the previous site stay until you remove them by hand.

Files go up first (the CSS, the images), then the pages and at the end the sitemap and the feed, so that a new page does not link to something that is not there yet. If the deployment is cut off, the next one picks up where it left off.

Each destination¶

With SFTP, the first time the deployment stops and tells you the fingerprint of the server. Check it with whoever administers it and write it down in sitio.yml (huella:): that way you know you are uploading to the server you think and not to another.

Passwords¶

They always go in .secretos.yml, in single quotes. Without the quotes, YAML reads some passwords differently without warning: what comes after # is a comment, and one that starts with !, *, @ or % is not even read. If a single quote is part of the password, it is written twice ('my''pass'). And if you put a password in sitio.yml, the deployment stops.

When you change the address of the site¶

Ehundu records in .ehundu.json which site the destination belongs to. If it does not match the url in your sitio.yml, it stops before touching anything. The usual cause is a wrong ruta, for example in a sitio.yml copied from another site that shares the server, and deploying there would delete everything belonging to the other one.

If it is the same site with another address (another domain, with www or without it, from http to https), you confirm it with --todo (“all”):

php ehundu.phar desplegar --todo

It uploads everything even if it has not changed, and it is also what you need if somebody has touched the files on the server by hand.

What it does not do¶

Nothing after deploying: it does not notify other services or empty the cache of a CDN. There are no environment variables for passwords. And there is no locking: if two machines deploy the same site at the same time, the .ehundu.json file can end up wrong. It is fixed with --todo.

The detail is in deployment (in Spanish) and in sitio.yml (in Spanish).