service/survey.md

-Tor Project runs a self-hosted instance of [LimeSurvey](https://www.limesurvey.org/) to conduct user research and feedback collection.
+Tor Project runs a self-hosted instance of [LimeSurvey](https://www.limesurvey.org/) CE (community edition) to conduct user research and collect feedback.
 
-The URL for this service is https://survey.torproject.org
+The URL for this service is https://survey.torproject.org/
+
+The onionv3 address is http://eh5esdnd6fkbkapfc6nuyvkjgbtnzq2is72lmpwbdbxepd2z7zbgzsqd.onion/
 
 [[_TOC_]]
 
+# Tutorial
+
+## Create a new account
+
+ 1. Login to the [admin interface][] (see `tor-passwords` repo for credentials)
+ 2. Navigate to `Configuration` -> [User management][]
+ 3. Click the `Add user` button on the top left corner
+ 4. Fill in `Username`, `Full name` and `Email` fields
+ 5. If `Set password now?` is left at `No`, a welcome email will be sent to the email address
+ 6. Select the appropriate roles in the `Edit permissions` table:
+   * For regular users who should be able to create and manage their surveys, select the `Permission to create surveys` / `General` checkbox
+
+[User management]: https://survey.torproject.org/index.php/userManagement/index
+
 # How-to
 
 ## Upgrades
 
-We don't use the paid [ComfortUpdate](https://community.limesurvey.org/comfort-update-extension/) extension that is heavily promoted by LimeSurvey.
+We don't use the paid [ComfortUpdate][] extension that is promoted and sold by LimeSurvey.
 
-Instead, we checkout release tags from a copy of the [GitHub repository](https://github.com/LimeSurvey/LimeSurvey).
+Instead, we deploy from the latest stable zip-file release using Puppet.
 
 The steps to upgrade LimeSurvey are:
 
- 0. `cd /srv/limesurvey`
- 1. Stop Apache2 using `systemctl stop apache2 puppet-run.timer` (no maintenance mode in LimeSurvey)
- 2. Fetch new git tags from upstream with `git fetch`
- 3. Checkout latest tag in 5.x series, eg. `git checkout 5.3.28+220727`
- 4. Run database upgrade `sudo -u www-data php application/commands/console.php updatedb`
- 5. Resume Apache2 `systemctl start apache2 puppet-run.timer`
- 6. Login to the [admin interface](https://survey.torproject.org/admin) and validate running version number
+ 1. Login to `survey-01`, stop Apache2 using `systemctl stop apache2 puppet-run.timer` (no maintenance mode in LimeSurvey)
+ 2. Open the [LimeSurvey latest stable release page][] and note the version number and sha256 checksum
+ 3. In the `tor-puppet` repository, edit `hiera/roles/survey.yaml` and update the version and checksum keys with above info
+ 4. Run the puppet agent on `survey-01`
+ 5. Puppet will unpack the new archive under `/srv/www/survey.torproject.org/${version}`, update the Apache vhost config and run the database update script
+ 6. Login to the [admin interface][] and validate the new version is running
+
+Because LimeSurvey does not make available previous release zip-files, the old code installation directory is kept on the server, along with prevously downloaded release archives. This is intentional, to make rolling back easier in case of problems during an upgrade.
+
+[ComfortUpdate]: https://community.limesurvey.org/comfort-update-extension/
+[LimeSurvey latest stable release page]: https://account.limesurvey.org/stable-release
+[admin interface]: https://survey.torproject.org/admin
 
 ## Disaster recovery
 
-In case of a disaster restoring both `/srv/limesurvey` and the PostgreSQL database on a new server should be sufficient to get back up and running.
+In case of a disaster restoring both `/srv` and the PostgreSQL database on a new server should be sufficient to get back up and running.
 
 # Reference