Move an existing nginx config across
If you already run nginx, you do not have to type all of it in again. This reads your existing configuration and turns it into sites and pools, and it writes nothing until you say so.
The important thing first
Pasting a configuration in and pressing the preview button writes nothing at all. It reads your text, works out what it would make, and shows you. You can point it at your live configuration purely to see what this makes of it, and then walk away.
Even after you import, nothing is live. Everything arrives switched off and unapplied.
Step 1: get the right file
Not the top level nginx.conf
It is usually just a list of includes, so pasting it shows you almost nothing and looks like the import is broken. On most systems the sites live in sites-enabled or conf.d.
cat /etc/nginx/sites-enabled/*If your configuration is split across several files, paste them one after another into the same box, or import them one at a time. Order does not matter.
Step 2: read the preview properly
Press See what it would make. The page splits what it found into three parts.
| Section | What to do with it |
|---|---|
| Pools | Check the servers and ports. Rename anything cryptic now, because renaming later means updating whatever points at it. |
| Sites | Check the names, the mode and the paths. Read the notes under each one. |
| Left alone | Read this properly. It is everything that could not become a setting, with the reason. Nothing is dropped silently. |
Each entry has a tick box. Untick anything you do not want. A common reason is an old site you have been meaning to retire, and the import is a good moment to not bring it with you.
Step 3: understand the notes
| A note like this | Means |
|---|---|
| The plain http block only redirected to https, so it became the force https switch | You had two server blocks for one name, one of which only forwarded to the other. That is one site here with a switch on, not two sites. |
| Paths were brought over, so each keeps its own backend | Your location blocks became paths on the site. |
| Some directives had no setting here, so they were kept as custom config | Anything without a box on the screen is preserved as raw configuration on the site rather than dropped. |
| No certificate was attached | This always happens and it is not an error. See below. |
Step 4: sort out certificates
Certificates are never brought across. Your configuration names certificate files by path, those paths point at files on the machine the config came from, and the private keys are not in the text you pasted anyway.
So each site comes across knowing it uses https and with no certificate chosen. Two options:
- Get a new one from Let's Encrypt, which is usually easiest. If the name still points at the old server, use dns-01 validation so you do not have to move traffic first.
- Upload the existing certificate and key, which is right when the certificate was bought and has time left on it.
Step 5: do the import
- Untick anything you do not want.
- Press Import the ticked ones.
- Go to Backend Pools and check the servers are right.
- Go to Sites and open each one. Check the names, the mode and the paths.
- Turn each site on when you are happy with it.
Do not import and apply in one go on a busy day
The import brings everything across switched off precisely so you can read it first. Applying immediately gives up that safety for no gain at all.
Step 6: cut over without downtime
The new fleet is now configured and nothing is pointing at it. That is a good place to be.
- Test without moving anything. Ask the new node directly with a Host header:
Or add the new address to your own hosts file and browse it normally.curl -sk -H "Host: shop.example.com" https://203.0.113.10/ -o /dev/null -w "%{http_code}\n" - Lower the TTL on the names you are moving, well in advance. A day ahead is not too early.
- Move one name at a time. Start with the least important thing you have.
- Watch it for longer than feels necessary before moving the next one.
- Keep the old server running until you are certain, because moving back is the same DNS change in reverse and it is nice to have somewhere to move back to.
Afterwards
Once everything is across, go back to the Left alone list from the import and work out whether any of it still matters. Some of it will be things you no longer need. Some of it belongs in the raw config box on a site, where it is stored and survives every apply.