We're glad you want to setup your machine for hitobito development 💃
You need to have Docker and docker-compose installed on your computer. The free Docker Community Edition (CE) works perfectly fine. Make sure your user is part of the docker group:
usermod -a -G docker $USERYou probably have to log out and log in back again or run newgrp docker.
Additionally you need git to be installed and configured.
🐧 This manual focuses on Linux/Ubuntu. Hitobito development also runs on other platforms with some adjustments. Follow the prerequisites in section Windows preparation to set up a Windows platform for Hitobito development, before continuing below.
First declare a instance name: (e.g. generic, pbs)
read -p "Enter hitobito instance name: " INSTANCE_NAMEThen you need to clone this repository:
mkdir -p ~/git/hitobito && cd ~/git/hitobito
git clone https://github.com/hitobito/development.git $INSTANCE_NAME && cd $INSTANCE_NAME
(cd app && git clone https://github.com/hitobito/hitobito.git)Now you need to add at least one wagon project:
# wagon project(s)
(cd app && git clone https://github.com/hitobito/hitobito_generic.git)⚡ If you want to contribute to an existing wagon/organisation please adapt this e.g. (cd app && git clone https://github.com/hitobito/hitobito_youth.git && git clone https://github.com/hitobito/hitobito_pbs.git)
The final structure in app/ should look something like this:
$ ls -lah app/
total 16K
drwxrwxr-x 4 ps ps 4.0K Jun 25 11:20 .
drwxrwxr-x 17 ps ps 4.0K Jun 25 10:00 ..
-rw-r--r-x 1 ps ps 2 Jun 25 10:00 .gitignore
drwxrwxr-x 18 ps ps 4.0K Jun 25 07:29 hitobito
drwxrwxr-x 11 ps ps 4.0K Jun 24 10:53 hitobito_genericIf you did not so before, create new docker volumes for storing bundled gems and yarn packages:
docker volume create hitobito_bundle
docker volume create hitobito_yarn_cache⚡ If your user id is not 1000 (run id -u to check), you need to export this as env variable: export RAILS_UID=$UID before running any of the further commands. Maybe you want to add this to your bashrc.
To start the Hitobito application, run the following command in your shell:
docker-compose up -d⚡ This will also install all required gems and seed the database, which takes some time to complete if it's executed the first time. You can follow the progress using docker-compose logs --follow rails (exit with Ctrl+C).
After the startup has completed (once you see Listening on tcp://0.0.0.0:3000 in the logs), make sure all services are up and running:
docker-compose psThis should look something like this:
Name Command State Ports
----------------------------------------------------------------------------------------------------------
development_cache_1 docker-entrypoint.sh memca ... Up 11211/tcp
development_db_1 docker-entrypoint.sh --sor ... Up 0.0.0.0:33066->3306/tcp, 33060/tcp
development_mailcatcher_1 container-entrypoint mailc ... Up 0.0.0.0:1080->1080/tcp, 8080/tcp
development_rails_1 rails-entrypoint rails ser ... Up 0.0.0.0:3000->3000/tcp, 8080/tcp
development_rails_test_core_1 rails-entrypoint sleep inf ... Up
development_sphinx_1 sphinx-start Up 36307/tcp
development_webpack_1 webpack-entrypoint /usr/sr ... Up 0.0.0.0:3035->3035/tcp
development_worker_1 rails-entrypoint rails job ... Up 8080/tcp
The _sphinx_1 container seems to be flaky. You can safely ignore a state Exit 2.
Access the web application by browser: http://localhost:3000 and log in using hitobito@puzzle.ch and password hito42bito. For some wagons, the e-mail address is different. Go to the file /config/settings.yml inside your wagon repository and look out for the field "root_email". Use this e-mail address to login.
📧 All mails sent by your local development environment end up in mailcatcher. You can access these e-mails by visiting http://localhost:1080.
Start developing by editing files locally with your prefered editor in the app/hitobito* folders. Those directories are mounted inside the containers. So every saved file is instantly available inside the containers.
💡 If you don't know where to begin changing something, have a look at our hitobito cheatsheet in English and German.
For executing tasks like rails routes or starting the rails console in development environment, run the following command:
docker-compose exec rails bashEither, to run tests for the core:
bin/test_env_coreor, to run tests for a wagon:
export WAGON=MYWAGON # e.g. WAGON=pbs
bin/test_env_wagonEither, to run all tests
rspecor, to run specific tests:
rspec spec/models/person_spec.rb
# To run a capybara feature spec, which runs inside a real browser, pass the following flag:
rspec --tag type:feature spec/features/person/person_tags_spec.rbFor debugging with pry during a HTTP request, you can attach to the running docker container (detach with Ctrl+c):
bin/attach_to_railsbin/database_console🍺 finished work ? execute docker-compose down to shut down all running containers
📆 If you have installed a previous development setup before 03.2021, please run the following command inside one project, and then update your images:
docker-compose down && docker volume rm hitobito_bundle && docker volume create hitobito_bundleWhen the images of this project change, execute the following command to update them locally:
docker-compose build --no-cache:race_car: You go ahead and clone your hitobito dev setup by taking full advantage of the hitobito_clone script located within bin/hitobito_clone.rb
Make sure you execute the script in the folder you want to have your hitobito setup. Make sure you have the following things preinstalled on your device:
# For script exec
- Ruby
# To retrieve the script
- wget
# Local development with docker
- docker + docker-compose
# Version control
- git
Then execute the following, which clones all hitobito repositories within a new or existing hitobito directory.
wget -O - https://raw.githubusercontent.com/hitobito/development/master/bin/hitobito_clone.rb | ruby*Note: by adding the -h option, you get some good information about what the script is able to do further.
The suggested approach for Hitobito development on Windows uses VSCode. VSCode provides extensions for integration of Docker and WSL 2. The next steps will prepare Windows for WSL 2, Docker and VSCode.
Install WSL 2 with Ubuntu using PowerShell running as administrator.
wsl --installConsider a look at Install Linux on Windows with WSL for troubleshooting.
Next, you will have to reboot your computer, before you are able to use WSL 2.
Open another PowerShell as administrator, and install Ubuntu:
wsl --install -d UbuntuAn Ubuntu terminal opens. If not, open Ubuntu using the Start menu.
You will be prompted to specify user name and password. Then, update and upgrade packages.
sudo apt update && sudo apt upgrade
⚡ Don't close the Ubuntu terminal yet.
Download and install Docker Desktop. The installation will promt you to enable WSL 2.
Open Docker Desktop using the Start menu. Select Settings > Generals and make sure the Use the WSL 2 based engine option is activated. If necessary, click Apply & restart.
Return to the Ubuntu terminal and confirm the installation.
docker --version
Version and build information should appear. That's it, terminate Ubuntu.
exit
See Get started with Docker remote containers on WSL 2 for a more detailed description.
Download and install VSCode.
Open VSCode using the Start menu.
Search for and install the following extensions:
- Remote Development (Microsoft)
- Dev Containers (Microsoft)
- Docker (Microsoft)
💡 You will find the Extensions menu on the left.
Start a remote Ubuntu session by clicking on the buttom left corner which should be highlighted in green, and select New WSL window.
A new VSCode instance opens with remote Ubuntu enabled. Confirm the button in the bottom left corner highlighted in green and indicating the Ubuntu session.
Start the terminal within VSCode, by clicking the Toggle panel button in the top right.
✨ Well done! You are set to follow the instructions of section Preparation, using the Ubuntu session within the VSCode terminal.
Hitobito has official support for nextcloud. You can start a nextcloud instance ready and set up for OIDC authentication via hitobito as follows:
docker-compose -f docker-compose.yml -f nextcloud.yml upYou can then access your local nextcloud instance at http://localhost.
To test the hitobito Login part, you can then click on "Login with hitobito".
Alternatively, to manage the local nextcloud, you can use the credentials admin / hito42bito.
In case you get the following error:
Client-Autorisierung MKIM ist fehlgeschlagen: Unbekannter Client, keine Autorisierung mitgeliefert oder Autorisierungsmethode nicht unterstützt.
The reason is that the connection between hitobito and nextcloud is set up during hitobito's seeding process, and you probably already had a seeded database before, so no re-seed was done. To fix it, you first have to clear your database and then start again:
# Clear the database
docker-compose -f docker-compose.yml -f nextcloud.yml down --volumes
# Start again
docker-compose -f docker-compose.yml -f nextcloud.yml up
# Now it should work