From 4a0518d79c163dee7c6d9709a5e71220c572c146 Mon Sep 17 00:00:00 2001
From: kez <kez@torproject.org>
Date: Fri, 17 Mar 2023 13:50:11 -0700
Subject: [PATCH] Update and expand on tor-weather docs

---
 service/tor-weather.md | 44 ++++++++++++++++++++++++++++++------------
 1 file changed, 32 insertions(+), 12 deletions(-)

diff --git a/service/tor-weather.md b/service/tor-weather.md
index 954e2c7c..df589ad3 100644
--- a/service/tor-weather.md
+++ b/service/tor-weather.md
@@ -1,4 +1,4 @@
-<!-- include a simple overview of the service here -->
+Tor-weather is a web service that alerts relay operators about issues with their relays. It runs on the host weather-01.
 
 [[_TOC_]]
 
@@ -79,10 +79,9 @@ because tor-weather is managed using [poetry][], there are a few steps necessary
 ### Installing on the server
 
 1. using the dependencies list from the previous section, install all dependencies that are available in the debian repos
-1. create a tor-weather directory to house the virtual environment, and configuration file: `mkdir -p /home/weather/tor-weather && cd /home/weather/tor-weather`
-1. create a vritual environment: `python3 -m venv --system-site-packages venv` and source it: `. venv/bin/activate`
+1. create a vritual environment: `python3 -m venv --system-site-packages tor-weather-venv` and source it: `. tor-weather-venv/bin/activate`
 1. install the remaining dependencies from requirements.txt: `pip install -r requirements.txt`
-1. create a file named `env` in the `tor-weather` directory with the following contents, replacing `<database password>` with the password you created for the torweather user in [Creating the postgres database][]:
+1. the /home/weather/.tor-weather.env file configures the tor-weather application through environment variables. This file is managed by puppet
 
 ```
 SMTP_HOST=localhost
@@ -94,7 +93,7 @@ SMTP_SSL='false'
 SQLALCHEMY_DATABASE_URI='postgresql+psycopg2://torweather:<database password>@localhost:5432/torweather'
 
 API_URL='https://onionoo.torproject.org'
-BASE_URL='https://weather-01.torproject.org'
+BASE_URL='https://weather.torproject.org'
 
 # XXX: change this
 JWT_SECRET='CHANGEME'
@@ -113,9 +112,28 @@ SECRET_KEY='secret'
 
 ## Upgrades
 
-<!-- how upgrades are performed. preferably automated through Debian -->
-<!-- packages, otherwise document how upgrades are performed. see also -->
-<!-- the Testing section below -->
+1. download a pre-built wheel from the [tor-weather ci][] or build one locally with poetry
+1. upload the wheel to the tor-weather machine with `scp tor_weather-0.1.0-py3-none-any.whl weather-01.torproject.prg:~/`
+1. activate the tor-weather virtualenv
+1. install the wheel: `pip install tor_weather-0.1.0-py3-none-any.whl`
+1. restart the service: `sudo -u weather env XDG_RUNTIME_DIR=/run/user/$(id -u weather) systemctl --user restart tor-weather.service`
+
+[tor-weather ci]: <https://gitlab.torproject.org/tpo/network-health/tor-weather/-/pipelines>
+
+## Migrating the database schema
+
+After an upgrade or an initial deployment, you'll need to create or migrate the database schema. This script will activate the tor-weather virtual environment, export the tor-weather envvar settings, and then create/migrate the database schema.
+
+```
+sudo -u weather bash
+cd /home/weather
+source tor-weather-venv/bin/activate
+set -a
+source .tor-weather.env
+set +a
+python -m tor_weather.data_model
+exit
+```
 
 ## SLA
 
@@ -146,7 +164,9 @@ tor-weather is backed by a postgres database. the postgres database is configure
 
 ## Queues
 
-<!-- email queues, job queues, schedulers -->
+### Onionoo Update Job
+
+The `tor-weather-onionoo.service` and `tor-weather-onionoo.timer` files run a job every 15 minutes to update tor-weather's onionoo metrics information. Tor-weather handling its own job scheduling is a planned feature.
 
 ## Interfaces
 
@@ -154,7 +174,7 @@ tor-weather is backed by a postgres database. the postgres database is configure
 
 ## Authentication
 
-<!-- SSH? LDAP? standalone? -->
+tor-weather handles its own user creation and authentication via the web interface.
 
 ## Implementation
 
@@ -162,8 +182,7 @@ tor-weather is backed by a postgres database. the postgres database is configure
 
 ## Related services
 
-<!-- dependent services (e.g. authenticates against LDAP, or requires -->
-<!-- git pushes)  -->
+- [Postgres](/howto/postgresql)
 
 ## Issues
 
@@ -196,6 +215,7 @@ tor-weather is maintained by the [network-health team][].
 
 <!-- where are the logs? how long are they kept? any PII? -->
 <!-- what about performance metrics? same questions -->
+Logs are kept in `<working directory>/logs`. In the current deployment this is `/home/weather/tor-weather/logs`.
 
 ## Backups
 
-- 
GitLab