Skip to content

Commit 9928948

Browse files
committed
Document initial setup procedure
1 parent d8b8f2c commit 9928948

File tree

1 file changed

+93
-2
lines changed

1 file changed

+93
-2
lines changed

README.md

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,12 @@ the server with consistent settings.
3131
Setup
3232
-----
3333

34-
Before you can run our ansible playbooks, you need to meet the following
34+
Before you can run our Ansible playbooks, you need to meet the following
3535
prerequisites:
3636

3737
* Create a DigitalOcean API token, and pass it to the inventory generator by
3838
setting the `DO_API_TOKEN` environment variable.
39-
* Set the vault decryption password of the ansible vaulted file with our
39+
* Set the vault decryption password of the Ansible vaulted file with our
4040
secrets. This may be done by setting the `ANSIBLE_VAULT_PASSWORD_FILE`
4141
environment variable to point to a file containing the password.
4242
* Download all the collections the playbooks depend on with the following
@@ -55,3 +55,94 @@ There is currently only one playbook:
5555

5656
* `matplotlib.org.yml`, for the main matplotlib.org hosting. This playbook
5757
operates on droplets with the `website` tag in DigitalOcean.
58+
59+
Provisioning a new server
60+
=========================
61+
62+
Naming
63+
------
64+
65+
We follow a simplified version of the naming scheme on [this blog
66+
post](https://mnx.io/blog/a-proper-server-naming-scheme/):
67+
68+
* Servers are named `<prefix>.matplotlib.org` in A records.
69+
* Servers get a functional CNAME alias (e.g., `web01.matplotlib.org`).
70+
* matplotlib.org is a CNAME to the functional CNAME of a server.
71+
72+
We use [planets in our Solar System](https://namingschemes.com/Solar_System)
73+
for the name prefix. When creating a new server, pick the next one in the list.
74+
75+
Initial setup
76+
-------------
77+
78+
The summary of the initial setup is:
79+
80+
1. Create the droplet with monitoring and relevant SSH keys.
81+
2. Assign new droplet to the matplotlib.org project and the Web firewall.
82+
3. Grab the SSH host fingerprints.
83+
4. Reboot.
84+
85+
We currently use a simple $5 droplet from DigitalOcean. You can create one from
86+
the control panel, or using the `doctl` utility. Be sure to enable monitoring,
87+
and add the `website` tag and relevant SSH keys to the droplet. An example of
88+
using `doctl` is the following:
89+
90+
```
91+
doctl compute droplet create \
92+
--image fedora-35-x64 \
93+
--region tor1 \
94+
--size s-1vcpu-1gb \
95+
--ssh-keys <key-id>,<key-id> \
96+
--tag-name website \
97+
--enable-monitoring \
98+
venus.matplotlib.org
99+
```
100+
101+
Note, you will have to use `doctl compute ssh-key list` to get the IDs of the
102+
relevant SSH keys saved on DigitalOcean, and substitute them above. Save the ID
103+
of the new droplet from the output, e.g., in:
104+
105+
```
106+
ID Name Public IPv4 Private IPv4 Public IPv6 Memory VCPUs Disk Region Image VPC UUID Status Tags Features Volumes
107+
294098687 mpl.org 1024 1 25 tor1 Fedora 35 x64 new website monitoring,droplet_agent
108+
```
109+
110+
the droplet ID is 294098687.
111+
112+
113+
You should also assign the new droplet to the `matplotlib.org` project and the
114+
`Web` firewall:
115+
116+
```
117+
doctl projects list
118+
# Get ID of the matplotlib.org project from the output.
119+
doctl projects resources assign <project-id> --resource=do:droplet:<droplet-id>
120+
121+
122+
doctl compute firewall list
123+
# Get ID of the Web firewall from the output.
124+
doctl compute firewall add-droplets <firewall-id> --droplet-ids <droplet-id>
125+
```
126+
127+
Then, to ensure you are connecting to the expected server, you should grab the
128+
SSH host keys via the DigitalOcean Droplet Console:
129+
130+
```
131+
for f in /etc/ssh/ssh_host_*_key; do
132+
ssh-keygen -l -f $f;
133+
done
134+
```
135+
136+
Note down the outputs to verify later, e.g.,
137+
138+
```
139+
# Use these for comparison when connecting yourself.
140+
1024 SHA256:ExviVyBRoNKsZpgmIfBaejh1ElOpJ/9fC+ki2Fn5Xj4 [email protected] (DSA)
141+
256 SHA256:hLA7ePr0D4AgiC21IXowtbpcUNnTGgpPB7NOYepQtxg [email protected] (ECDSA)
142+
256 SHA256:MggFZQbZ7wID1Se2EmOwAm8AaJeA97L8sD8DhSrKy1g [email protected] (ED25519)
143+
3072 SHA256:MCkDgfbn0sMTCtvAtfD0HmGJV3LVTjpUj6IcfWRHRQo [email protected] (RSA)
144+
```
145+
146+
Finally, you should reboot the droplet. This is due to a bug in cloud-init on
147+
DigitalOcean, which generates a new machine ID after startup, causing system
148+
logs to be seem invisible.

0 commit comments

Comments
 (0)