Updates Baremetal deploy to use git clone and branch names

[cannikin]

Currently you can only update your codebase via git pull during a baremetal deploy. This is fraught with danger, mostly because yarn.lock doesn't really seem to function as an immutable lock file, and will sometimes be changed when running yarn install on the server. If yarn.lock is changed then git pull will fail because there are uncommitted changes.

A safer way to do code updates is to actually clone the whole repo from scratch with git clone --depth=1 which will retrieve the latest state of the code without all the history.

Breaking

Unfortunately this is a breaking change to anyone using the baremetal deploy option. To get this working properly I removed the current pull strategy altogether, and now also require you to install pm2 globally instead of just inside your app's dependencies (this was required because of the way the directories are now nested: you need to run the pm2 commands outside of the app directory, and yarn pm2 won't work from there).

Closes #5082
Closes #5083
Closes #5084

Release Notes

We've got a good news/bad news situation if you're using the new Baremetal deploy option released in v1.0.0! Good news: you can now deploy a branch other than main and code updates are much more reliable using git clone! The bad news is that you're going to have to do some more config and server setup to get this latest version working. But once you do, everything will be awesome!

PM2

Baremetal now requires that PM2 be installed globally, rather than a development dependency of your app. This has to do with the new directory structure we're going to create and where pm2 is executed from (short version: it's run outside of your actual codebase, so yarn pm2 won't be available).

You'll want to remove your existing pm2 services. This will cause downtime, so be mindful if running in a production environment. Run the following commands on the server:

yarn pm2 delete all

Now install PM2 globally: https://pm2.io/docs/runtime/guide/installation/

PM2 will still be running in memory as the previous yarn pm2 version, so you can run this command to update the process:

pm2 update

If you previously setup PM2 to run at startup, you'll need to update to the new global install instead:

yarn pm2 unstartup
pm2 startup

Be sure to remove pm2 in your app's package.json file.

Directory Structure

Next we'll need to update the directory structure inside your deploy path.

Current directory structure:

└── var
    └── www
        └── myapp
            ├── api
            ├── web
            ├── ...

New directory structure:

└── var
    └── www
        └── myapp
            ├── .env <────────────┐
            ├── current ────────┐ │
            └── 20220420120000 <┘ │
                ├── .env ─────────┘
                ├── api
                ├── web
                ├── ...

The current symlink is updated at the end of a deploy to point to the latest release (assuming a successful clone and build). This means all build packages in web/dist and api/dist remain self-contained in their parent timestamp directory. This makes a rollback trivial: just point the current symlink to the previous directory and restart your web/api processes! yarn rw deploy baremetal --rollback is coming soon! A shared .env file exists in the root of your app path and each copy of the codebase will contain a symlink back out to this file.

The easiest way to update to this structure is to simply remove everything inside of your currently deploy directory (like /var/www/myapp) and let yarn rw deploy baremetal --first-run set everything up for you. You'll want to keep your .env file, however:

cd /var/www/myapp
mv .env ..
rm -rf *
mv ../.env .

Config Updates

You'll need to add a new option to your ecosystem.config.js file for any processes that run within the context of your app:

module.exports = {
  apps: [
    {
      name: 'serve',
+     cwd: 'current',
      script: 'node_modules/.bin/rw',
      args: 'serve',
      instances: 'max',
      exec_mode: 'cluster',
      wait_ready: true,
      listen_timeout: 10000,
    }
}

You'll also need to add the repo config setting and optionally branch to your deploy.toml file:

[[servers]]
host = "myserver.com"
username = "user"
agentForward = true
sides = ["api", "web"]
path = "/var/www/myapp"
processNames = ["api"]
+ repo = "[email protected]:myorg/myrepo.git"
+ branch = "main"

The branch will default to main if not set.

Make sure everything is saved, committed, and pushed up to your repo because we're ready for the first deploy.

First Deploy

Run the deploy command for the first time to setup the directory structure, check out your code, and build and start monitoring your processes:

yarn rw deploy baremetal --first-run

And that's it! If everything started up correctly then you're good to go for future deploys. If not check out https://redwoodjs.com/docs/deployment/baremetal#troubleshooting

If you want to perform a one-time deploy of a branch other than the one listed in deploy.toml you can do so via a flag at deploy time:

yarn rw deploy baremetal --branch=staging

[netlify]

✅ Deploy Preview for redwoodjs-docs ready!

Name	Link
🔨 Latest commit	90b227b
🔍 Latest deploy log	https://app.netlify.com/sites/redwoodjs-docs/deploys/6266f7708c0a7a00080cd532
😎 Deploy Preview	https://deploy-preview-5282--redwoodjs-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[cannikin]

@thedavidprice how do we want to handle breaking changes going forward? Does this just merge like everything else, or do we need to wait until 2.0 now?? This is a breaking change for anyone using baremetal deploy, which I'd hazard a guess is probably in the single-digit number of users.

[zpeters]

This is amazing, can't wait to try to it out!

[cannikin]

Consolidated in #5500

[zpeters]

I love seeing progress on this!