Migrate an existing application to Pierrr

Before you start

This checklist collects what comes up in practice when you bring an application that already runs somewhere else onto your own server. Go through it in order: each point avoids a failed deploy or an outage.

• A server of yours is connected to Pierrr and its setup assistant is finished. See Servers.
• Your code provider is connected to the organization, with access to the repositories to migrate. See Organizations.
• You have a recent, encrypted backup of your data (database, files uploaded by your users) and a copy of the server's current configuration. Do not start without them.
• You have written down the current DNS records of each domain: they are your way back.

Health route

Pierrr checks each container with a request on a health path, and only sends traffic to a new version if it answers properly. A wrong health route is the first cause of a cancelled deploy.

• Create a health route if there is none: it must answer 200 without depending on a session, a database or an external service.
• It must answer both GET and HEAD requests. Some frameworks only declare GET: a HEAD probe then gets an error and the application is seen as down while it works.
• If your route is not /health, set its path in the application's build settings (Repositories tab). The default path is not guessed.
• A HEALTHCHECK written in your Dockerfile is ignored: do not maintain it twice. See Projects.

A dedicated Dockerfile

The Dockerfile used by your current CI is often designed for another environment: it assumes secrets, steps or a registry that do not exist here.

• Prefer a Dockerfile written for Pierrr, in the repository, over reusing your CI's as is. When the repository has one, Pierrr uses it without replacing it.
• Without a Dockerfile, Pierrr offers a template suited to the framework: the install, build and start commands stay yours.
• The pre-build check flags common mistakes (a LABEL line before the first FROM, missing dependencies): read its warnings before the first deploy.
• The application must listen on the declared port, on all interfaces, not only on localhost.

Monorepo projects

When one repository holds several services (an API, a side service, several sites), each service becomes its own application in the same Pierrr project.

• Create one application per service, each linked to the same repository with the path of its own Dockerfile.
• Turn on "Monorepo: build from the repository root" when the Dockerfile lives in a subfolder but the build needs to see the whole repository (shared packages, lock file at the root). The build context is then the root.
• In that case, write the Dockerfile's COPY paths relative to the repository root, not to the subfolder.
• Give each application its own health path and its own port: do not assume they are shared.

Build memory on a small server

A build often uses far more memory than the running application. On a small server the builder is capped, and a build can be stopped for lack of memory with a message that says little.

• Cap the build tool's memory, for example by limiting the Node heap with NODE_OPTIONS=--max-old-space-size in the Dockerfile, to a value below the server's memory.
• Turn off what the build does not need: source maps, bundle analysis, checks run in parallel.
• Do not run several heavy deploys at once on the same machine: chain them.
• A deploy that fails with "insufficient memory" is fixed by capping the build or giving the machine more memory, not by retrying.

Import secrets without copying them elsewhere

Your environment variables hold keys that must not pass through any chat tool, ticket or email.

• From your own machine, open the project's vault and use bulk edit: paste the .env block straight into the dialog, the preview counts additions and replacements before applying. See Projects.
• Never paste a .env file into a chat, a ticket or a message: if that happened, change the keys involved.
• Drop the variables that no longer matter in the new environment (internal hosts of the old server, CI tokens).
• Public values read by the browser must be read on the server at startup, not frozen at build time.

Database

On your server, the project's database is created on the machine, never at Pierrr. You restore an export of the old database into it.

• Export the old database as one SQL file, then restore it with "Import my data" in the Backups tab, by sending the file or giving its https address.
• A large database takes several minutes to copy: let the dialog follow progress and do not restart the import.
• If the old database holds orphan rows (references to deleted rows), the restore can fail on a constraint: clean the orphans at the source, or import with those constraints left unvalidated and fix them afterwards.
• Then compare the row counts of the main tables between the old and the new database before going on.

Cache and volumes

The cache and the volumes of a project on your server are included: they are added at no cost.

• Add the cache to the project if the application needs it, then link it explicitly to the container: a resource only reaches a container if you connect it there.
• Create a volume for each folder to keep (uploaded files, local data) and attach it to the container with its mount path, in the Topology.
• Copy the contents of the old folders into the new volumes before the switch, then check they are visible from the application.
• A cache's contents do not need to be migrated: they rebuild.

Domains

A domain served by your server is set up with an A record to the machine's public IP address.

• Add each host separately (root, www, subdomains) and link each to the right service: one host, one service. See Domains.
• Create one A record per host to the server's public IP address, and leave your mail records alone.
• The certificate is issued for each host separately, once the DNS is right and port 80 is reachable from the Internet. With several hosts, some certificates arrive a few minutes after the others: Pierrr retries by itself, and "Retry TLS" retries on demand.
• Lower the records' time to live (TTL) before the switch so that a rollback is quick.

Turn off automatic deployment during trials

While the old installation still serves your visitors, a push must not restart the builds of every service without you having decided it.

• In the Repositories tab, turn off the "Auto-deploy" switch of each application during the trial phase. A push on the watched branch then starts nothing.
• Deploy by hand, application by application, and wait for each build to finish before starting the next.
• Turn the switch back on only once the switch-over is done and checked.

Switching ports 80 and 443, and rolling back

A server can only serve your domains if ports 80 and 443 are free. If another program holds them (the machine's old web server), your applications' public access does not come up and a failure badge says so.

• First check the application on its Pierrr address, with its real data, before touching the ports.
• At the chosen moment, stop the old program holding ports 80 and 443, then let Pierrr sync the applications' public access, or run the sync again.
• Rollback: keep the old configuration and the old program ready to restart. To go back, stop public access on the Pierrr side, restart the old program on ports 80 and 443, and put back the old DNS records you wrote down at the start if needed.
• Do not delete the old database, the old files folder or the old configuration before several days of stable operation.

Final checks

Before you consider the migration done, go through this list on each domain.

• Each host answers over https with a valid certificate and no browser warning.
• Each application is healthy in Pierrr, and the last deploy is a success.
• The important journeys work with real data: sign-in, file upload, test payment, email sending.
• The old installation's scheduled tasks are taken over, and not run twice.
• A data backup is run on the new project and its result is checked.
• Automatic deployment is back on, and the old installation is only removed after a few days.