Skip to content

dev_environment.md

Latest commit

 

History

History
95 lines (68 loc) · 5.99 KB

dev_environment.md

File metadata and controls

95 lines (68 loc) · 5.99 KB

Development Environment

Install Docker

First, you need to have Docker and Docker Compose installed on your system.

Environment variables

Create a .env file in the root of the repository and write needed environment variables to it. You can take the Example .env and fill in couple of the variables according to the Environment variable docs.

Creating self-signed certificates

Using openssl on linux, run in project root folder:

mkdir certs
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./certs/privkey.pem -out ./certs/fullchain.pem
sudo openssl dhparam -out nginx/certs/dhparam.pem 4096

More details here

Initializing the database with existing database (eg. staging database)

mariadb-dump -h {DB_HOST} -P {DB_PORT} -u {DB_USERNAME} -p {DB_NAME} > db.dump
docker compose up -d db
docker compose exec -T db mariadb -u {ROOT_USERNAME} -p {DB_NAME} < db.dump

Running the environment

To start the environment, you have to run this command in the root the repository.

docker-compose up -d --build

Now if you go to localhost:8000, you should see the RNames app running. You can also go to localhost:8001 to see or modify the created database. If the website doesn't show up, check the logs. Most likely the service just hasn't started yet.

You can make changes to the django app in real time when the containers are running. The App directory has been binded to the rnames_web container so that all the changes to the host machine's App directory are also made in the container.

To see logs you can run this command. You can also specify a container if you only want to see specific logs docker-compose logs -f <container>.

docker-compose logs -f

NOTE: The logs may show a failure to run tests unless proper privileges for Django have been set. This is normal; see Running tests.

If you want to shutdown the containers, you can run this command.

docker-compose down

In the case of wanting to also remove the volumes (meaning that the database will be reset), you can run docker-compose down -v.

Other useful commands

You can execute commands inside the container by running:

docker-compose exec <container> <command>

For example, if you need to make migrations inside django, you can run docker-compose exec web python manage.py makemigrations. Then to migrate the database you can run docker-compose exec web python manage.py migrate. These commands should usually been run when the developer has made changes to the models or created a new app inside django. See more in Django docs.

Please note that currently the django application makes migrations and migrates the database every time the django container is started. If this proves to be cumbersome the lines can be commented out in entrypoint.sh.

User groups and permissions

RNames does not require user registration/login for viewing. However, adding, editing or exporting data is restricted to three user groups:

  • registered users can export certain data as .csv files.
  • data contributors can add data to the database as well as edit or delete their own contributions.
  • data admins can freely add, edit or delete data in the database.

These restrictions are enforced by the code, but setting up the user groups and adding new users in the database must currently be done manually. Once the containers are running, open Django Admin in a web browser: http://localhost:8000/admin/. The site will ask you to log in; by default the username is admin and the password is password. To add a group, click on Add under Authentication and Authorization – Groups.

  • Enter a name for the group. The name should be either registered, data_contributor or data_admin, depending on which group is currently being created.
  • Grant permissions to the group. In the current implementation, groups data_contributor and data_admin have been granted all permissions (with more specific restrictions being handled by the code). This can be done simply by clicking on Choose all under the Permissions list. Group registered has been granted all viewing permissions; type view into the Filter field and then click on Choose all.
  • Save the group by clicking Save.

To add a user, click on Add under Authentication and Authorization – Users.

  • Enter a username, password and e-mail address for the user. Note that these must be unique for each user. Other fields are optional.
  • Select a group for the user from the group list and add it by clicking on the right-pointing arrow button between the lists. It is technically possible to add more than one group, but there is no need for it in the current implementation; e.g. the group registered does not have any permissions that data_contributor or data_admin do not have.
  • Save the user by clicking Save.

When signing in as a new user in RNames for the first time, the application is supposed to send a verification link to the user’s e-mail address (and will claim to have done so), but due to how the e-mail backend is currently configured, this does not actually happen. One way to verify a user’s e-mail address is the following:

  1. Attempt to sign in as the new user in RNames.
  2. Navigate to http://localhost:8001/
  3. Open the database table account_emailaddress under django_rnames.
  4. Click Edit on the e-mail address to be verified, and enter 1 into the columns verified and primary.

Paleobiology database migration

To run the Paleobiology database migration, the country codes from county_codes.csv must be imported into the database with column order iso3166_1_alpha_2, official_name_en, region_name