docs: add/update API, web server and other manuals (#38650)
This commit is contained in:
Mrugesh Mohapatra
GitHub
parent
c5ba18e978
commit
feab0cabcb
@ -9,10 +9,11 @@
|
||||
- [How to catch outgoing emails locally](/how-to-catch-outgoing-emails-locally.md)
|
||||
- **<i class="fad fa-laptop-code"></i> DevOps Guides**
|
||||
- [How we build, test and deploy](/devops.md)
|
||||
- **<i class="fad fa-plane-alt"></i> Flight Manuals (for Staff & Mods)**
|
||||
- [01 - List Virtual Machines](/flight-manuals/01-getting-list-of-virtual-machines.md)
|
||||
- [02 - Work on API Instances](/flight-manuals/02-spinning-api-instances.md)
|
||||
- [03 - Using Reply Templates](/flight-manuals/03-using-reply-templates.md)
|
||||
- **<i class="fad fa-plane-alt"></i> Flight Manuals** (for Staff & Mods)
|
||||
- [Using Reply Templates](/flight-manuals/using-reply-templates.md)
|
||||
- [Work on Virtual Machines](/flight-manuals/working-on-virtual-machines.md)
|
||||
- [Work on API Instances](/flight-manuals/working-on-api-instances.md)
|
||||
- [Work on Web Server Instances](/flight-manuals/working-on-web-server-instances.md)
|
||||
----
|
||||
- **<i class="fad fa-user-friends"></i> Our Community**
|
||||
- [**<i class="fab fa-github"></i> GitHub Repository**](https://github.com/freecodecamp/freecodecamp)
|
||||
|
||||
@ -1,52 +0,0 @@
|
||||
# Getting a list of the Virtual Machines
|
||||
|
||||
As a member of the staff or the dev-team, you may have been given access to our cloud vendors like Azure, Digital Ocean, etc. Here are some handy commands that you can use to list the Public IP addresses for the Virtual machine instances that are live and deployed.
|
||||
|
||||
> [!NOTE]
|
||||
> You may already have SSH access, but it will not let you list VMs unless you also have access to the vendor portals themselves.
|
||||
|
||||
## Azure
|
||||
|
||||
Install Azure CLI `az`: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
|
||||
|
||||
> **(One-time) Install on macOS with [`homebrew`](https://brew.sh):**
|
||||
|
||||
```
|
||||
brew install azure-cli
|
||||
```
|
||||
|
||||
> **(One-time) Login:**
|
||||
|
||||
```
|
||||
az login
|
||||
```
|
||||
|
||||
> **Get the list of VM names and IP addresses:**
|
||||
|
||||
```
|
||||
az vm list-ip-addresses --output table
|
||||
```
|
||||
|
||||
## Digital Ocean
|
||||
|
||||
Install Digital Ocean CLI `doctl`: https://github.com/digitalocean/doctl#installing-doctl
|
||||
|
||||
> **(One-time) Install on macOS with [`homebrew`](https://brew.sh):**
|
||||
|
||||
```
|
||||
brew install doctl
|
||||
```
|
||||
|
||||
> **(One-time) Login:**
|
||||
|
||||
Authentication and context switching: https://github.com/digitalocean/doctl#authenticating-with-digitalocean
|
||||
|
||||
```
|
||||
doctl auth init
|
||||
```
|
||||
|
||||
> **Get the list of VM names and IP addresses:**
|
||||
|
||||
```
|
||||
doctl compute droplet list --format "ID,Name,PublicIPv4"
|
||||
```
|
||||
@ -2,23 +2,17 @@
|
||||
|
||||
## Installing pre-requisites
|
||||
|
||||
Perform updates to packages
|
||||
1. Perform updates to the OS packages by following [this guide](flight-manuals/working-on-virtual-machines).
|
||||
|
||||
```console
|
||||
sudo apt update
|
||||
sudo apt upgrade -y
|
||||
sudo apt autoremove -y
|
||||
```
|
||||
2. Install build tools for node binaries (`node-gyp`) etc.
|
||||
|
||||
Install tools for binaries (`node-gyp`) etc.
|
||||
```console
|
||||
sudo apt install build-essential
|
||||
```
|
||||
|
||||
```console
|
||||
sudo apt install build-essential
|
||||
```
|
||||
## First Install
|
||||
|
||||
## First Install
|
||||
|
||||
### Provisioning VMs with the Code
|
||||
Provisioning VMs with the Code
|
||||
|
||||
1. Install Node LTS.
|
||||
|
||||
@ -71,37 +65,43 @@ pm2 monitor
|
||||
|
||||
## Updating Instances (Maintenance)
|
||||
|
||||
### Rolling updates for logical changes to code
|
||||
Code changes need to be deployed to the API instances from time to time. It can be a rolling update or a manual update. The later is essential when changing dependencies or adding enviroment variables.
|
||||
|
||||
> [!NOTE]
|
||||
> We are handling rolling updates to code, logic, via pipelines. You do not need to run these commands. These are here for documentation.
|
||||
> [!DANGER]
|
||||
> The automated pipelines are not handling dependencies updates at the minute. We need to do a manual update before any deployment pipeline runs.
|
||||
|
||||
### 1. Manual Updates - Used for updating dependencies, env variables.
|
||||
|
||||
1. Stop all instances
|
||||
|
||||
```console
|
||||
pm2 stop all
|
||||
```
|
||||
|
||||
2. Install dependencies
|
||||
|
||||
```console
|
||||
npm ci
|
||||
```
|
||||
|
||||
3. Build the server
|
||||
|
||||
```console
|
||||
npm run ensure-env && npm run build:server
|
||||
```
|
||||
|
||||
4. Start Instances
|
||||
|
||||
```console
|
||||
pm2 start all --update-env && pm2 logs
|
||||
```
|
||||
|
||||
### 2. Rolling updates - Used for logical changes to code.
|
||||
|
||||
```console
|
||||
pm2 reload all --update-env && pm2 logs
|
||||
```
|
||||
|
||||
### Stop and start updates for changes in dependencies
|
||||
> [!NOTE]
|
||||
> We are handling rolling updates to code, logic, via pipelines. You do not need to run these commands. These are here for documentation.
|
||||
|
||||
1. Stop all instances
|
||||
|
||||
```console
|
||||
pm2 stop all
|
||||
```
|
||||
|
||||
2. Install dependencies
|
||||
|
||||
```console
|
||||
npm ci
|
||||
```
|
||||
|
||||
3. Build the server
|
||||
|
||||
```console
|
||||
npm run ensure-env && npm run build:server
|
||||
```
|
||||
|
||||
4. Start Instances
|
||||
|
||||
```console
|
||||
pm2 start all --update-env && pm2 logs
|
||||
```
|
||||
84
docs/flight-manuals/working-on-virtual-machines.md
Normal file
84
docs/flight-manuals/working-on-virtual-machines.md
Normal file
@ -0,0 +1,84 @@
|
||||
# Working on Virtual Machines
|
||||
|
||||
|
||||
As a member of the staff or the dev-team, you may have been given access to our cloud vendors like Azure, Digital Ocean, etc.
|
||||
|
||||
Here are some handy commands that you can use to work on the VMs, for instance performing maintenance updates or doing general houeskeeping.
|
||||
# Keeping Virtual Machines Updated
|
||||
|
||||
You should keep the Virtual Machines up to date by performing updates and upgrades. This will ensure that the virtual machine is patched with latest security fixes.
|
||||
|
||||
> [!WARNING]
|
||||
> Before you run these commands:
|
||||
> - Make sure that the VM has been provisioned completely and there is no post-install steps running.
|
||||
> - If you are updating packages on a VM that is already serving an application, make sure the app has been stopped / saved. Package updates will cause network bandwidth, memory and/or CPU usage spikes leading to outages on running applications.
|
||||
|
||||
Update package information
|
||||
|
||||
```console
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
Upgrade installed packages
|
||||
|
||||
```console
|
||||
sudo apt upgrade -y
|
||||
```
|
||||
|
||||
Cleanup unused packages
|
||||
|
||||
```console
|
||||
sudo apt autoremove -y
|
||||
```
|
||||
|
||||
# Getting a list of the Virtual Machines
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> You may already have SSH access to virtual machines, but that alone will not let you list VMs unless you also have access to the vendor portals as well.
|
||||
|
||||
## Azure
|
||||
|
||||
Install Azure CLI `az`: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
|
||||
|
||||
> **(One-time) Install on macOS with [`homebrew`](https://brew.sh):**
|
||||
|
||||
```
|
||||
brew install azure-cli
|
||||
```
|
||||
|
||||
> **(One-time) Login:**
|
||||
|
||||
```
|
||||
az login
|
||||
```
|
||||
|
||||
> **Get the list of VM names and IP addresses:**
|
||||
|
||||
```
|
||||
az vm list-ip-addresses --output table
|
||||
```
|
||||
|
||||
## Digital Ocean
|
||||
|
||||
Install Digital Ocean CLI `doctl`: https://github.com/digitalocean/doctl#installing-doctl
|
||||
|
||||
> **(One-time) Install on macOS with [`homebrew`](https://brew.sh):**
|
||||
|
||||
```
|
||||
brew install doctl
|
||||
```
|
||||
|
||||
> **(One-time) Login:**
|
||||
|
||||
Authentication and context switching: https://github.com/digitalocean/doctl#authenticating-with-digitalocean
|
||||
|
||||
```
|
||||
doctl auth init
|
||||
```
|
||||
|
||||
> **Get the list of VM names and IP addresses:**
|
||||
|
||||
```
|
||||
doctl compute droplet list --format "ID,Name,PublicIPv4"
|
||||
```
|
||||
57
docs/flight-manuals/working-on-web-server-instances.md
Normal file
57
docs/flight-manuals/working-on-web-server-instances.md
Normal file
@ -0,0 +1,57 @@
|
||||
# Work on Web Server instances
|
||||
|
||||
We are running load balanced (Azure Load Balancer) instances for our web servers. These servers are running NGINX which reverse proxy all of the traffic to freeCodeCamp.org from various applications running on their own infrastructures.
|
||||
|
||||
The NGINX config is available on [this repository](https://github.com/freeCodeCamp/nginx-config).
|
||||
|
||||
## Installing pre-requisites
|
||||
|
||||
Perform updates to the OS packages by following [this guide](flight-manuals/working-on-virtual-machines).
|
||||
|
||||
## First install
|
||||
|
||||
> TODO - Detailed Instructions
|
||||
|
||||
1. Provision a VM on Azure.
|
||||
2. Install NGINX and configure from repository.
|
||||
3. Inatall Cloudflare origin certificates and upstream application config.
|
||||
4. Setup networking and firewalls.
|
||||
5. Add the VM to the load balancer backend pool.
|
||||
|
||||
|
||||
## Logging and Monitoring
|
||||
|
||||
1. Check status for NGINX service using the below command:
|
||||
|
||||
```console
|
||||
sudo systemctl status nginx
|
||||
```
|
||||
|
||||
2. Logging and monitoring for the servers are available at:
|
||||
|
||||
> <h3 align="center"><a href='https://amplify.nginx.com' _target='blank'>https://amplify.nginx.com</a></h3>
|
||||
|
||||
## Updating Instances (Maintenance)
|
||||
|
||||
Config changes to our NGINX instances are maintained on GitHub, these should be deployed on each instance like so:
|
||||
|
||||
1. SSH into the instance and enter sudo
|
||||
|
||||
```console
|
||||
sudo su
|
||||
```
|
||||
|
||||
2. Get the latest config code.
|
||||
|
||||
```console
|
||||
cd /etc/nginx
|
||||
git fetch --all --prune
|
||||
git reset --hard origin/master
|
||||
```
|
||||
|
||||
3. Test and reload the config [with Signals](https://docs.nginx.com/nginx/admin-guide/basic-functionality/runtime-control/#controlling-nginx).
|
||||
|
||||
```console
|
||||
nginx -t
|
||||
nginx -s reload
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user