public-health-ch/README.md

153 lines
5.7 KiB
Markdown
Raw Normal View History

Public Health Schweiz
=====================
2017-10-23 07:42:52 +00:00
Website of the [Swiss Society for Public Health](http://public-health.ch), developed by [datalets,ch](http://datalets.ch) using the open source, [Django](https://www.djangoproject.com/)-based [Wagtail CMS](http://wagtail.io). The frontend is implemented by [moving water](http://www.movingwater.ch/) using [Bootstrap](https://getbootstrap.com) framework.
2017-04-25 14:05:02 +00:00
2017-05-05 14:10:24 +00:00
This project is open source under the [MIT License](LICENSE.md).
[![Dependency Status](https://dependencyci.com/github/datalets/public-health-ch/badge)](https://dependencyci.com/github/datalets/public-health-ch)
2016-12-12 22:43:20 +00:00
## Development environment
The easiest way to set up your machine would be to use [Vagrant](https://vagrantup.com), then in the project folder in the terminal type: `vagrant up`. Then when it is ready, follow instructions for *publichealth/static/org/archive-message.html#Database setup*.
To set up a full development environment, follow all these instructions.
**Frontend setup**
2018-06-02 12:37:25 +00:00
Make sure a recent version of node.js (we recommend using [nave.sh](https://gipublichealth/static/org/archive-message.htmlthub.com/isaacs/nave)), then:
```
npm install -g yarn grunt-cli
yarn install
```
The first command (`..install -g..`) may require `sudo` if you installed node.js as a system package. Afterwards, to compile the frontend, you should be able to run:
`grunt`
2018-07-13 05:48:32 +00:00
If you are only working on the frontend, you can start a local webserver and work on frontend assets without the backend setup described below. There is a `grunt browser-sync` setup for working with frontend assets.
2019-08-09 13:19:50 +00:00
(In a Vagrant shell, use the alias `watch`)
2016-12-14 09:43:06 +00:00
**Backend setup**
2017-05-09 14:57:54 +00:00
If not using Vagrant: after installing Python 3, from the project folder, deploy system packages and create a virtual environment as detailed (for Ubuntu users) below:
2016-12-12 22:43:20 +00:00
```
2016-12-19 10:32:58 +00:00
sudo apt-get install python3-venv python3-dev libjpeg-dev
pyvenv env
. env/bin/activate
pip install -U pip
pip install -r requirements.txt
2017-05-09 14:57:54 +00:00
```
At this point your backup is ready to be deployed.
## Database setup
Once your installation is ready, you can get a blank database set up and add a user to login with.
2017-05-09 14:57:54 +00:00
If you are using Vagrant, enter the shell of your virtual machine now with `vagrant ssh`
Run these commands:
```
./manage.py migrate
./manage.py createsuperuser
2016-12-12 22:43:20 +00:00
```
2016-12-12 22:44:06 +00:00
2016-12-14 09:43:06 +00:00
You will be asked a few questions to create an administrator account.
**Starting up**
2016-12-14 09:43:06 +00:00
If you have one installed, also start your local redis server (`service redis start`).
2017-05-09 14:57:54 +00:00
After completing setup, you can use:
2016-12-14 09:43:06 +00:00
```
2017-05-03 06:51:43 +00:00
./manage.py runserver
2016-12-12 22:44:06 +00:00
```
2016-12-14 09:43:06 +00:00
2017-05-09 14:57:54 +00:00
(In a Vagrant shell, just use `djrun`)
2017-05-03 06:51:43 +00:00
Now access the admin panel with the user account you created earlier: http://localhost:8000/admin/
2017-03-03 17:13:31 +00:00
## Troubleshooting
2021-02-20 14:00:04 +00:00
Issues with migrating database tables in SQLite during development? Try `./manage.py migrate --fake`
2021-02-20 14:34:47 +00:00
Trouble installing packages with npm or yarn? Add IPv6 addresses to your hosts:
2021-02-20 14:00:04 +00:00
2021-02-20 14:34:47 +00:00
2606:4700:10::6814:162e nodejs.org
2021-02-20 14:00:04 +00:00
2606:4700::6810:1823 registry.npmjs.org
2606:4700::6810:1123 registry.yarnpkg.com
2021-02-20 14:34:47 +00:00
2a0a:e5c0:2:10::8c52:790a codeload.github.com
2017-03-27 21:32:32 +00:00
## Production notes
We use [Ansible](https://www.ansible.com) and [Docker Compose](https://docs.docker.com/compose/reference/overview/) for automated deployment.
2018-12-17 12:50:15 +00:00
To use Docker Compose to manually deploy the site, copy `ansible/roles/web/templates/docker-compose.j2` to `/docker-compose.yml` and fill in all `{{ variables }}`. This can also be done automatically in Ansible.
2021-02-20 14:00:04 +00:00
To update all roles from [Ansible Galaxy](https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html) used in our install scripts:
2018-12-17 12:50:15 +00:00
```
2021-02-20 14:00:04 +00:00
ansible-galaxy install `ls ansible/roles -x -I wagtail` --force
2018-12-17 12:50:15 +00:00
```
2017-05-03 22:28:59 +00:00
2018-12-18 00:05:58 +00:00
To check that the scripts and roles are correctly installed, use this command to do a "dry run":
```
2021-02-18 15:40:18 +00:00
ansible-playbook ansible/*.yaml -i ansible/inventories/lagoon --list-tasks
2020-05-16 13:12:07 +00:00
```
If you only want to run a certain set of actions, subset the tags which you see in the output above. For example, to only update the NGINX configuration:
```
2021-02-18 15:40:18 +00:00
ansible-playbook ansible/web.yaml -i ansible/inventories/lagoon --tags "nginx_template_config"
2018-12-18 00:05:58 +00:00
```
2017-05-03 22:28:59 +00:00
2017-05-05 14:35:06 +00:00
To do production deployments, you need to obtain SSH and vault keys from your system administrator (who has followed the Ansible guide to set up a vault..), and place these in a `.keys` folder. To deploy a site:
```
2021-02-18 15:40:18 +00:00
ansible-playbook ansible/*.yaml -i ansible/inventories/lagoon
2017-05-05 14:35:06 +00:00
```
2020-05-16 13:12:07 +00:00
For an update release with a specific version (tag or branch), use (the `-v` parameter showing output of commands):
2017-05-05 14:35:06 +00:00
```
2021-02-18 15:40:18 +00:00
ansible-playbook ansible/site.yaml -i ansible/inventories/lagoon --tags release -v -e gitversion=<v*.*.*>
```
2020-05-16 13:43:10 +00:00
You can also use the `gitrepo` parameter to use a different fork of the source code.
2020-05-15 22:14:14 +00:00
Once the basic system set up, i.e. you have an `ansible` user in the sudoers and docker group, you are ready to run the playbook.
2017-06-02 10:52:15 +00:00
### Production releases
2017-04-26 13:37:15 +00:00
For further deployment and system maintenance we have a `Makefile` which automates Docker Compose tasks. This should be converted to use [Ansible Container](http://docs.ansible.com/ansible-container/getting_started.html). In the meantime, start a release with Ansible, then complete it using `make`, i.e.:
```
2021-02-18 15:40:18 +00:00
ansible-playbook -i ansible/inventories/lagoon --tags release ansible/wagtail.yaml
2017-04-26 13:57:01 +00:00
ssh -i .keys/ansible.pem ansible@<server-ip> "cd <release_dir> && make release"
2017-04-26 13:37:15 +00:00
```
2017-05-09 14:57:54 +00:00
2019-01-10 09:38:52 +00:00
This is already part of the normal release cycle, but if you wish to update the Docker images to the latest versions separately, use:
`make upgrade`
2017-05-09 14:57:54 +00:00
### Restoring a data backup
For development, it's handy to have access to a copy of the production data. To delete your local database and restore from a file backup, run:
```
rm publichealth-dev.sqlite3
python manage.py migrate
python manage.py loaddata publichealth.home.json
```
You might want to `createsuperuser` again at this point.