Skip to content

Commit 6c77945

Browse files
turukawaturukawa
committed
Update to 0.7.3 release
1 parent 0c920d6 commit 6c77945

File tree

2 files changed

+316
-0
lines changed

2 files changed

+316
-0
lines changed

‎DEPLOYMENT-README.md

+311
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
# Step-by-step production deployment guide
2+
3+
There are easier ways to run a blog. You will find the resource requirements for this stack quite substantive. This really is if you intend to run some complex web service and need all the architecture.
4+
5+
> **NOTE**: this is a more focused, step-by-step version of the generated "README". You will find a few more details there, especially about customising larger deployments, or changing your configuration after deployment. This is designed to get you up-and-running with your first production deployment in a controlled way. No guarantees, though.
6+
7+
## Preparation
8+
9+
### Committing to GitHub
10+
11+
Prepare your code and resources for your first commit. There are three files which must **not** be committed unless you're quite positive your data will never leak.
12+
13+
- `/.env`
14+
- `/cookiecutter-config-file.yml`
15+
- `/frontend/.env`
16+
17+
These files will also need to be customised for production deployment. Make alternative arrangements for these files. Don't trust `.gitignore` to save you.
18+
19+
### DigitalOcean Droplets
20+
21+
This guide uses [DigitalOcean Droplets](https://www.digitalocean.com/pricing/droplets), so customise as required. Deploy to the smallest (currently 500MiB memory, 1 vCPU and 10GiB SSD for $4/month). You can upgrade later when you know your resource requirements.
22+
23+
> **WARNING**: if you're using `neo4j` then the `java` server alone will need 1Gb of memory, and you may need a 2Gb to 4Gb base droplet. Plan accordingly. If you decide not to use it, you will need to carefully remove it. That will require editing `docker-compose.yml` and the start-up sequence in the backend. Shouldn't be too challenging.
24+
25+
Ensure you add your SSH encryption keys on launch so that your server can be secure from the beginning.
26+
27+
Deploy on whatever server image your prefer, although the default would be Ubuntu 20.04 (22.04 is the latest). End-of-life for 20.04 is April 2030, and for 22.04 is April 2032. You have time. The underlying image isn't that critical, as you'll be using the Docker images at their current versions.
28+
29+
### Domain name and email
30+
31+
Get your settings and redirects at your registrar, and then set up the various DNS records at DigitalOcean, pointing at the IP address for the droplet you set up.
32+
33+
For reference:
34+
- [Link Namecheap domain to DigitalOcean](https://www.namecheap.com/support/knowledgebase/article.aspx/10375/2208/how-do-i-link-a-domain-to-my-digitalocean-account/)
35+
- [Manage DNS records at DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/)
36+
37+
Don't forget to create DNS A records for `flower`, `neo4j`, `traefik`, and `pgadmin`.
38+
39+
Now you should be able to login to your server and begin deployment.
40+
41+
## Deployment
42+
43+
### Docker
44+
45+
Update your server, and install all required packages:
46+
47+
```shell
48+
# Install the latest updates
49+
apt-get update
50+
apt-get upgrade -y
51+
```
52+
53+
Then:
54+
55+
```shell
56+
# Download Docker
57+
curl -fsSL get.docker.com -o get-docker.sh
58+
# Install Docker using the stable channel (instead of the default "edge")
59+
CHANNEL=stable sh get-docker.sh
60+
# Remove Docker install script
61+
rm get-docker.sh
62+
```
63+
64+
### Clone your repository
65+
66+
The basic approach is to clone from GitHub then set up the appropriate `.env` files and any custom `conf` files called from `docker-compose`. If yours is a private repo, review the GitHub docs for how to set that up.
67+
68+
Remember you can create new passwords as follows:
69+
70+
```bash
71+
openssl rand -hex 32
72+
# Outputs something like: 99d3b1f01aa639e4a76f4fc281fc834747a543720ba4c8a8648ba755aef9be7f
73+
```
74+
75+
From `/srv`:
76+
77+
```shell
78+
git clone https://github.com/<user-name>/<project-name>.git
79+
```
80+
81+
Then continue from the project directory `/srv/<project-name>`. You can always pull your latest code from that directory, with:
82+
83+
```shell
84+
git pull
85+
```
86+
87+
### Docker Swarm Mode
88+
89+
Deploy the stack to a Docker Swarm mode cluster with a main Traefik proxy, set up using the ideas from [DockerSwarm.rocks](https://dockerswarm.rocks). And you can use CI (continuous integration) systems to do it automatically.
90+
91+
This stack expects the public Traefik network to be named `traefik-public`.
92+
93+
```bash
94+
export USE_HOSTNAME=example.com
95+
```
96+
97+
```bash
98+
# Set up the server hostname
99+
echo $USE_HOSTNAME > /etc/hostname
100+
hostname -F /etc/hostname
101+
```
102+
103+
Set up **Swarm Mode**:
104+
105+
```shell
106+
docker swarm init
107+
```
108+
109+
If this fails, you'll need to explicitly link the public IP for the droplet:
110+
111+
```shell
112+
docker swarm init --advertise-addr 123.123.123.123
113+
```
114+
115+
You can add additional manager and worker nodes. This is optional and you can read the DockerSwarm.rocks link for more.
116+
117+
Check that the nodes are connected and running:
118+
119+
```shell
120+
docker node ls
121+
```
122+
123+
Which would output something like:
124+
125+
```
126+
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
127+
ndcg2iavasdfrm6q2qwere2rr * dog.example.com Ready Active Leader 18.06.1-ce
128+
```
129+
130+
### Traefik Proxy with HTTPS
131+
132+
Follow the documentation from DockerSwarm.rocks to [get automatic HTTPS certificates](https://dockerswarm.rocks/traefik/).
133+
134+
Create a network that will be shared with Traefik and the containers that should be accessible from the outside, with
135+
136+
```shell
137+
docker network create --driver=overlay traefik-public
138+
```
139+
140+
Get the Swarm node ID of this node and store it in an environment variable (use the code below exactly):
141+
142+
```shell
143+
export NODE_ID=$(docker info -f '{{.Swarm.NodeID}}')
144+
```
145+
146+
Create a tag in this node, so that Traefik is always deployed to the same node and uses the same volume:
147+
148+
```shell
149+
docker node update --label-add traefik-public.traefik-public-certificates=true $NODE_ID
150+
```
151+
152+
Create an environment variable with your email, to be used for the generation of Let's Encrypt certificates, e.g.:
153+
154+
```shell
155+
export [email protected]
156+
```
157+
158+
Create an environment variable with the domain you want to use for the Traefik UI (user interface), e.g.:
159+
160+
```shell
161+
export DOMAIN=traefik.example.com
162+
```
163+
164+
You will access the Traefik dashboard at this domain, e.g. `traefik.example.com`.
165+
166+
Create an environment variable with a username (you will use it for the HTTP Basic Auth for Traefik and Consul UIs), for example:
167+
168+
```shell
169+
export USERNAME=admin
170+
```
171+
172+
Create an environment variable with the password, e.g.:
173+
174+
```shell
175+
export PASSWORD=changethis
176+
```
177+
178+
Use `openssl` to generate the "hashed" version of the password and store it in an environment variable:
179+
180+
```shell
181+
export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)
182+
```
183+
184+
Download the file `traefik.yml`:
185+
186+
```shell
187+
curl -L dockerswarm.rocks/traefik.yml -o traefik.yml
188+
```
189+
190+
Deploy the stack with:
191+
192+
```shell
193+
docker stack deploy -c traefik.yml traefik
194+
```
195+
196+
It will use the environment variables you created above. Check if the stack was deployed with:
197+
198+
```bash
199+
docker stack ps traefik
200+
```
201+
202+
It will output something like:
203+
204+
```
205+
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
206+
w5o6fmmln8ni traefik_traefik.1 traefik:v2.2 dog.example.com Running Running 1 minute ago
207+
```
208+
209+
You can check the Traefik logs with:
210+
211+
```bash
212+
docker service logs traefik_traefik
213+
```
214+
215+
### Deploy to a Docker Swarm mode cluster
216+
217+
There are 4 (5) steps:
218+
219+
1. **Pull** your git repo
220+
2. **Build** your app images
221+
3. **Deploy** your stack
222+
4. **Restart** your docker service
223+
224+
---
225+
226+
Here are the steps in detail:
227+
228+
1. **Pull** your git repo
229+
230+
```bash
231+
cd /srv/example
232+
```
233+
```bash
234+
sudo git pull
235+
```
236+
237+
2. **Build your app images**
238+
239+
* Set these environment variables, right before the next command:
240+
* `TAG=prod`
241+
* `FRONTEND_ENV=production`
242+
* Use the provided `scripts/build.sh` file with those environment variables:
243+
244+
```bash
245+
TAG=prod DOMAIN=example.com STACK_NAME=example-com TRAEFIK_TAG=example.com FRONTEND_ENV=production bash -x scripts/build.sh
246+
```
247+
248+
**Persisting Docker named volumes**
249+
250+
You can use [`docker-auto-labels`](https://github.com/tiangolo/docker-auto-labels) to automatically read the placement constraint labels in your Docker stack (Docker Compose file) and assign them to a random Docker node in your Swarm mode cluster if those labels don't exist yet.
251+
252+
To do that, you can install `docker-auto-labels`:
253+
254+
```bash
255+
pip install docker-auto-labels
256+
```
257+
258+
And then run it passing your `docker-stack.yml` file as a parameter:
259+
260+
```bash
261+
docker-auto-labels docker-stack.yml
262+
```
263+
264+
You can run that command every time you deploy, right before deploying, as it doesn't modify anything if the required labels already exist.
265+
266+
3. **Deploy your stack**
267+
268+
* Set these environment variables:
269+
* `DOMAIN=example.com`
270+
* `TRAEFIK_TAG=example.com`
271+
* `STACK_NAME=example-com`
272+
* `TAG=prod`
273+
* Use the provided `scripts/deploy.sh` file with those environment variables:
274+
275+
```bash
276+
DOMAIN=example.com TRAEFIK_TAG=example.com STACK_NAME=example-com TAG=prod bash -x scripts/deploy.sh
277+
```
278+
279+
4. **Restart** your docker service
280+
281+
```bash
282+
sudo service docker restart
283+
```
284+
285+
You may need to prune regularly while developing if you find yourself running out of space:
286+
287+
```shell
288+
docker system prune
289+
```
290+
291+
## URLs
292+
293+
These are the URLs that will be used and generated by the project.
294+
295+
### Production URLs
296+
297+
Production URLs, from the branch `production`.
298+
299+
Frontend: https://example.com
300+
301+
Backend: https://example.com/api/
302+
303+
Automatic Interactive Docs (Swagger UI): https://example.com/docs
304+
305+
Automatic Alternative Docs (ReDoc): https://example.com/redoc
306+
307+
PGAdmin: https://pgadmin.example.com
308+
309+
Flower: https://flower.example.com
310+
311+
Traefik: https://traefik.example.com

‎README.md

+5
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,11 @@ After using this generator, your new project (the directory created) will contai
217217

218218
See notes and [releases](https://github.com/whythawk/full-stack-fastapi-postgresql/releases).
219219

220+
### 0.7.3
221+
- @nuxt/content 2.2.1 -> 2.4.3
222+
- Fixed: `@nuxt/content` default api, `/api/_content`, conflicts with the `backend` api url preventing content pages loading.
223+
- Documentation: Complete deployment guide in `DEPLOYMENT-README.md`
224+
220225
### 0.7.2
221226
- Fixed: URLs for recreating project in generated `README.md`. PR [#15](https://github.com/whythawk/full-stack-fastapi-postgresql/pull/15) by @FranzForstmayr
222227
- Fixed: Absolute path for mount point in `docker-compose.override.yml`. PR [#16](https://github.com/whythawk/full-stack-fastapi-postgresql/pull/16) by @FranzForstmayr

0 commit comments

Comments
 (0)