To Start the MH Rails app locally:
- install docker: https://docs.docker.com/get-docker/
- run "make local_setup"
- run "make start" to stop all container
- run "make stop" to start all container
or any of the other targets in the Makefile
- run "make local"
set the TAG_MODULE_HANDBOOK=in target debug
- make debug
- make bash
(other options below)
Preparation:
- install docker: https://docs.docker.com/get-docker/
- create a new directory.
- Put the dump in it with the name module-handbook.pgdump
git clone git@github.com:modulehandbook/modulehandbook.git
cd modulehandbook make start make file=../module-handbook.pgdump init
This is a Ruby on Rails application using a Postgres Database and Devise for Authentication (heartcombo/devise: Flexible authentication solution for Rails with Warden.).
Bootstrap is used for the frontend.
The Modulehandbook is being designed and developed by a team within the joint project German International University of Applied Sciences (GIU AS) - Hochschule für Technik und Wirtschaft Berlin University of Applied Sciences - HTW Berlin in order to ease collaborative editing of the study programs for the GIU AS.
make start
The makefile contains useful commands; have a look at it.
make start
uses docker-compose up to start up the docker containers
- module-handbook
- module-handbook-exporter
- module-handbook-postgres It uses the Exporter specified in TAG_MODULE_HANDBOOK_EXPORTER set in the makefile.
see the makefile for details and settings
You can either create a new database with seed data or import a db dump:
- Seed Data:
make new_db
- Import Dump:
- with makefile:
make file=<dumpfile> import_dump
- Manually
- copy the db dump to ./pg_transfer which is mounted to cp ./pg_transfer/uas-module-handbook-cron-2022-11-23--13-00-00.pgdump
- open bash in pg container make bash_db
- restore the database: (alter the file name as needed!) pg_restore --verbose --clean --no-acl --no-owner -h localhost -U modhand -d modhand-dev /var/lib/postgresql/transfer/uas-module-handbook-cron-2022-11-23--13-00-00.pgdump
import for prod db: DBNAME=modhand-db-prod file=../uas-module-handbook-cron-2022-11-28--22-00-00.pgdump make import_dump
The Modulehandbook uses Devise for Authentication. New Users can register on the site themselves, but need to be approved by any admin (an existing user with role 'admin'). Furthermore, they need to confirm their email.
For this to work devise needs an email account configured for actionmailer. Create an email-Account and set these environment variables:
export HOSTNAME=
export DEVISE_EMAIL=
export SMTP_PORT=465
export SMTP_SERVER=smtp.strato.de
export SMTP_LOGIN=
export SMTP_PASSWORD=
bin/bundle install
bin/rails db:create
bin/rails db:migrate
bin/rails db:seed
This needs an open local Postgres running. Start postgres in docker container:
docker-compose -f docker-compose.yml up -d module-handbook-postgres
See the makefile for more useful commands.
docker-compose up
make new_db
heroku create
git push heroku master
heroku run rails db:migrate
heroku open
Devise sends emails to confirm new users and for password resets.
heroku config:set HOSTNAME=modulehandbook.server.com
heroku config:set SMTP_PORT=587
heroku config:set SMTP_SERVER=smtp.server.de
heroku config:set SMTP_LOGIN=email@server.com
heroku config:set SMTP_PASSWORD=geheim
heroku config:set DEVISE_EMAIL=email@server.com
heroku config:set SEED_USER_PW=<pw for users in seed>
heroku run rails db:seed RAILS_ENV=staging
(use RAILS_ENV=staging to avoid sending user creation email. This works on heroku as heroku overwrites and environment db config)
The seeds creates an example program for International Media and Computation at HTW Berlin with one user within each role. See db/seeds.rb
['admin@mail.de', :admin], ['reader@mail.de', :reader], ['writer@mail.de', :writer], ['editor@mail.de', :editor], ['qa@mail.de', :qa]
dumps are made with pg_dump -fC (special file format) which can be restored with pg_restore
- create production dump:
make dump_production
creates a file like ../mh-dumps/htw/modhand-2022-12-08--22-48-27.pgdump
- import to local dev db:
make import_dump_local
, e.g.
DBNAME=modhand-db-dev file=../mh-dumps/htw/modhand-2022-12-08--22-48-27.pgdump make import_dump_local
Manually, with the dumps mount in place and a current dump copied there: docker-compose exec postgresql bash pg_restore --verbose --clean --no-acl --no-owner -h localhost -U modhand -d modhand /var/lib/postgresql/dumps/uas-module-handbook-cron-2020-12-06--14-00-00.pgdump
or, use this for the container (also in makefile)
docker-compose exec postgresql pg_restore --verbose --clean --no-acl --no-owner -h localhost -U modhand -d modhand /var/lib/postgresql/$(file)
(Automation is done by heroku, see https://dashboard.heroku.com/apps/module-handbook-staging/deploy/github)
Everything in the branch staging is automatically deployed on the staging server. To trigger the automatic deployment to http://module-handbook-staging.herokuapp.com/ use the following steps:
git checkout staging
git pull origin master
git push
(Automation is done by heroku, see https://dashboard.heroku.com/apps/module-handbook/deploy/github)
Everything in the branch release is automatically deployed on the production server. To trigger the automatic deployment to http://module-handbook.herokuapp.com/ use the following steps:
git checkout release
git pull origin master
git push
git push heroku master
heroku run rake db:migrate
heroku pg:backups:capture
heroku pg:backups:download
(now automatically on one macos via crontab:)
0 * * * * bash && cd /Users/kleinen/mine/current/code/uas-module-handbook/module-handbook && make crondump
rails test
rails test:system
rails test test/** - runs all tests.
rails test
generates test coverage. does not work properly when calling rake/rake test
yarn add bootstrap jquery popper.js
flowchart TD
MHF --http--> MH
MH -- "html, css, json, docx" --> MHF
subgraph all["Module Handbook Architecture"]
subgraph front[Frontend]
MHF("Module Handbook Frontend\n(Browser)")
end
subgraph back["Backend: 3 Docker Containers on Server"]
MH("Module Handbook\n(Rails App)")
EX("Exporter\n(Javascript/Express App)")
DB[(Postgres)]
end
end
MH -- json --> EX
EX -- docx --> MH
MH <-- SQL --> DB
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf
- ./nginx/templates:/etc/nginx/templates
- ./container_logs/nginx:/var/log/nginx
- ./secrets/nginx:/etc/ssl
NGINX_CERT=/etc/ssl/production/module-handbook.f4.htw-berlin.de.cer NGINX_KEY=/etc/ssl/production/module-handbook.f4.htw-berlin.de.key NGINX_CERT=/etc/ssl/staging/module-handbook-staging.f4.htw-berlin.de.cer NGINX_KEY=/etc/ssl/staging/module-handbook-staging.f4.htw-berlin.de.key
The Dockerfile contains three targets. modhand-dev contains dev and test dependencies which are not needed in production.
- modhand-base
- modhand-prod
- modhand-dev
docker build --target modhand-prod .
local startup in prod environment:
docker-compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.localprod.yml up
see the makefile for various start/stop and database setup commands.
Git on windows automatically checks out all files from a Github repository with CRLF line separator which is problematic when building the docker image locally which runs on a linux machine, and creates a fatal error.
To disable this 'feature' before checking out repository
git config --global core.autocrlf false
If the files were already checked out, make sure to change docker-entrypoint.sh file and rails file to the LF line separator before building the image.
This can be done through several IDEs, or even through Notepad++(Edit -> EOL Conversion -> Unix)
sudo docker-compose up -d
sudo docker-compose down
docker stop module-handbook
docker-compose exec module-handbook bash
docker restart modulehandbook
docker ps
https://dbdiagram.io/d/639efdd399cb1f3b55a213d3
<iframe width="560" height="315" src='https://dbdiagram.io/embed/639efdd399cb1f3b55a213d3'> </iframe>