Skip to content

Latest commit

 

History

History
195 lines (140 loc) · 7.1 KB

INSTALLING.md

File metadata and controls

195 lines (140 loc) · 7.1 KB
Raw

Development setup for Constipated Koala

Koala is written using the Ruby on Rails framework, which uses the programming language Ruby. We use Nix to manage dependencies. (Also see the dependency managment readme). Rails is based on the Model-View-Controller paradigm, and has an easy to understand file structure. On the production server, we use Unicorn to run the application with multiple threads, and [Nginx] as a proxy. In both development and production, we use Mariadb as the database.

Requirements

To get started, you will need:

  • Preferably a Linux installation, but MacOS or WSL2 should work too
  • Git (sudo apt install git)
  • Nix (https://nixos.org/download.html)
    • You must use the multi-user installation!
    • If the installation fails, please remove any traces of old nix installations. After following these steps, make sure you log out of your system first!. This ensures all enviroment variables are set correctly.

To start, clone the project:

$ git clone git@github.com:svsticky/constipated-koala
Cloning into 'constipated-koala'...

To speed up the build, you can install and set up Cachix

$ nix-env -iA cachix -f https://cachix.org/api/v1/install
installing 'cachix-0.3.8'

**Warning**: Never run nix(-shell) as root! This should not be needed. Don't run it as root now, and not in other steps.

$ cachix use svsticky-constipated-koala
Configured https://svsticky-constipated-koala.cachix.org binary cache in ~/.config/nix/nix.conf

Now we can run nix-shell for the first time

$ nix-shell
[nix-shell:~/projects/koala.svsticky.nl]$

This should install all dependencies and launch a shell. Next time you'll call nix-shell will be a whole lot faster, don't worry.

Note

If you ever experience deep/difficult issues with seting up your nix-shell, now or during another step, this is probably because your environment variables (which are carried over to nix) are too smart for nix. If your environment variables are really the cause of the issue - or if you assume that this is the case - run nix-shell with the --pure argument. This tells nix to not 'copy' over any environment varibles. Running nix-shell with --pure is a last-resort solution, however.

Configuring Koala

To actually run Koala, you'll need a running copy of PostgreSQL and Redis To easily start both, you can run these in a container via Docker. Follow these steps to install Docker and start the database:

# Install Docker and Docker Compose
sudo apt install docker.io docker-compose

# Add yourself to the `docker` system group (needed only once)
# NOTE: You need to log out and log in again to apply this!
sudo usermod -aG docker $USER

# Install and start the database
# If you don't want to log out and log in again, use `sudo` here.
docker-compose up -d

PostgreSQL and Redis will now set itself up in the background, and will be available in a minute or so. You'll need to run the docker-compose up command again if you reboot your computer to start the database again. If you like, you can run the container in the background by adding -d to the mentioned command. If you're already running a copy of PostgreSQL, you can use this too.

The next command starts a process which enabled hot-reloading for the javascript and css. If you're not working on the front-end, you can skip this step.

bundle exec ./bin/webpack-dev-server

This command should also be executed from within a Nix shell. Thus, to run Koala correctly, these two processes should be running as well.

Moving on, there is an example file in the root of this repository called sample.env. This file is a template for the actual configuration file .env, which sets some configuration values for Koala. Copy sample.env to .env, and edit it according to the instructions in the file.

Once you're done, you can set up the database with this command (in the Nix shell):

rails db:setup

This creates the database for you and fills it with fake test data. It generates two users that you can use:

  • dev@svsticky.nl, an admin user (password is sticky123),
  • test@svsticky.nl, a member user (same password).

Then precompile the assets (in the Nix shell):

rails assets:precompile

Running Koala

You can run Koala itself by running this command (again, in the Nix shell):

rails server
# This works as well:
rails s

This will start a server that listens until you press Ctrl-C in the window where it's running.

The server will listen for connections from localhost, which means that it's only accessible from the computer where you're running the server. In order to have the server actually work, you'll need to run this command once:

echo "127.0.0.1    koala.rails.local members.rails.local leden.rails.local intro.rails.local" | sudo tee -a /etc/hosts

After this, when the server is running, you can open http://koala.rails.local:3000 in your browser, and you should get Koala's login screen.

Happy hacking!

Production

The development setup is set up to consume less resources, and to allow rapid development by automatically loading changed code. In production, we use a different setup to be able to handle more requests at once and to integrate with some of our other websites. If you're interested, you can view the script that is used to set up the actual Koala instance in the Sadserver repository under ansible/tasks/koala.yml.

Mailchimp synchronization

To utilize and set up the mailchimp synchronization have a look at MAILCHIMP.md.

Background jobs

There are some background jobs that need to be run periodically in production:

  • rails admin:start_year['Lidmaatschap',7.5], which starts a new study year when it's appropriate to do so.
  • rails status:mail, which should be run once a year, preferably in the summer holidays. The tasks asks appropiate members if they are still studying and if they are okay with us storing their data (our version of GDPR compliancy).

You shouldn't need to run these in development.

Database management

Some database commands that you might need if something breaks:

  • rails db:create: Create a database, but don't fill it with tables or data.
  • rails db:setup: Create the database and fill it with random test data. Doesn't work if there already is a database, but does delete your data!
  • rails db:reset: Delete and recreate the database, with new test data.
  • rails db:migrate: Apply all pending migrations. If the migrations are new, this will alter db/schema.rb. If this happens, commit this file!
  • rails db:rollback: Roll back the most recent migration.

See the migrations guide for more info on how migrations work.