Put your first site live
This takes one site from nothing to working, with a certificate, and then adds a second set of servers for part of it. Follow it with your own names in place of the example ones and you will have done most of the everyday jobs once.
The example
A company runs a shop. The application runs on two servers inside their network, and there is a separate pair running the part the mobile app talks to.
| Thing | Value |
|---|---|
| The address people type | shop.example.com |
| Web servers | 10.0.0.11 and 10.0.0.12, both on port 8080 |
| API servers | 10.0.0.21 and 10.0.0.22, both on port 9000 |
| Everything under /api | Should go to the API servers |
Step 1: a pool for the web servers
- Backend Pools, New pool.
- Name it
shop-web. - Add 10.0.0.11 port 8080, then 10.0.0.12 port 8080.
- Leave the balancing method as round robin.
- On the Health checks tab, turn checks on and set the type to HTTP. Point the path at a page that really exercises the application. If it does not have one, use
/for now and come back to it. - Save.
Wait a few seconds and look at the pool. Both servers should turn green. If they do not, stop here and fix it. Everything after this assumes the load balancer can reach your application, and a site in front of a pool that cannot answer only produces a more confusing version of the same problem.
Nothing you have done so far affects anybody
The pool exists in the screen and nginx has not been told about it.
Step 2: a pool for the API servers
Do the same again. Name it shop-api, add 10.0.0.21 and 10.0.0.22 on port 9000, and
check both go green.
Step 3: the site
- Sites, New site.
- Name it
shop. This is for you and visitors never see it. - Under server names, put
shop.example.com. - Set the mode to Proxy and choose
shop-web. - Leave Listen on http on. Leave Listen on https on. Leave the certificate empty for now.
- Create site.
Step 4: apply, and check the plain address
Press Apply config. It takes a few seconds and tells you which nodes took the change. Now check it over plain http, since there is no certificate yet.
curl -sI http://shop.example.com/ | head -3| What you get | What it means |
|---|---|
| 200 | It works. Go on to step 5. |
| 502 | The load balancer reached nginx but could not get an answer from your application. Go back to the pool and look at the members. |
| No answer at all | The name does not point at your load balancer yet, which is a DNS job rather than anything here. |
| Somebody else's site | Your server names do not match, or another site is the default. Check the server names field first. |
Step 5: the certificate
- Certificates, Get one from Let's Encrypt.
- Type
shop.example.com. - Press Request and wait about thirty seconds.
The certificate appears in the list marked valid, with the days remaining and how many nodes have a copy. It should say it reached all of them.
If this is your first certificate
Staging is on by default, so what you get is not trusted by browsers. That is deliberate: the real service allows five certificates a week for the same names with no way to appeal, and everybody gets the setup wrong at least once. Once you have one working, turn staging off in Settings and issue again.
Step 6: turn on https
- Open the site and choose the certificate you just got.
- Turn on Redirect http to https.
- Apply config.
Open it in a browser. You should get a padlock and no warning. The plain address should forward to the secure one.
Step 7: send /api somewhere else
- Open the site and find the Paths section.
- Add a path. Type
/api, match type Prefix. - Set it to send requests to a pool, and choose
shop-api. - Leave Take this path off before sending it on turned off, because the API application was written knowing it lives under
/api. - Save, then Apply config.
Add a path for the rest of the site
As soon as a site has any paths at all, it stops using the single backend on the Basics tab. Add a path of / pointing at shop-web as well, or everything except /api starts returning 404.
Step 8: prove the failover works
This is the step people skip and it is the one worth doing.
- Stop the application on 10.0.0.11, or take it off the network.
- Within a few seconds the pool should show that server red and the other green.
- The site should keep working throughout. Check it.
- Start it again and watch it come back.
If the pool never went red
Your health check is not testing anything useful. Point it at a page that genuinely exercises the application and try again. Finding this out now is much better than finding it out during a real failure.
What you have
A site on a real certificate that renews itself, spread across two servers, with part of it going to a different pair, and you have seen it survive one of them failing. That is the common shape of most of the work you will do here.