Getting Started

This quickstart results in this: Web Application

Including a nice admin interface: Admin Interface

1: Install dependencies on your system

Setup your system to run this software using your favourite package manager.

MacOS (brew)

brew install git python3 direnv

Debian Linux (apt)

apt-get install git python3 direnv

Redhat/CentOS (yum)

yum install git python3 direnv

Or download and install each package seperately:

  • git (download and install)
  • python3.6 (download and install)
  • Tox (pip3 install --user tox)
  • direnv (download and install, then follow setup instructions, see Direnv section below)
  • Docker (recommended, follow instructions to install.)

2: Install direnv correctly

Then set up direnv, the right command depends on your shell:

BASH Add the following line at the end of the ~/.bashrc file:

eval "$(direnv hook bash)"

Make sure it appears even after rvm, git-prompt and other shell extensions that manipulate the prompt.

ZSH Add the following line at the end of the ~/.zshrc file:

eval "$(direnv hook zsh)"

FISH Add the following line at the end of the ~/.config/fish/config.fish file:

eval (direnv hook fish)

TCSH Add the following line at the end of the ~/.cshrc file:

eval `direnv hook tcsh`

3: Generic install steps

Install Tox, which helps to install the rest of the dependancies of this project:

pip3 install --user tox

In a directory of your choosing:

download the software

git clone --recursive https://gitlab.com/failmap/failmap/

enter the directory of the downloaded software

cd failmap/

This prepares the shell environment for local development.

direnv allow

Running Tox once creates a development Virtualenv in .tox/default/ which is automatically used after creation due to Direnv setup. Running Tox without arguments by default also runs basic checks and tests to verify project code quality.

tox

After completing succesfully Failmap is available to run. For example, to show a list of commands:

failmap help

Now run the following command to start a full development server.

failmap devserver

Now visit the map website and/or the admin website at http://127.0.0.1:8000 (credentials: admin:faalkaart).

4. Optional Steps

This shows the current data on the map:

failmap rebuild_ratings

It is possible to start the server without redis and without (re)loading data:

failmap devserver --no-backend --no-data

Give everyone an F rating!

https://www.youtube.com/watch?v=a14Y2V5zJlY
https://www.youtube.com/watch?v=eAwq2QV7f1k

Troubleshooting

This repository uses submodules to pull in external dependencies. If you have not cloned the repository with --recursive or you need to restore the submodules to the expected state run:

git submodule update

Git submodules are an unreliable mess if you already have the system up and running. Updating submodules by force can be done using this command:

git submodule update --init --force --remote

About Versioning

Version for the project is losely semver with no specific release schedule or meaning to version numbers (eg: stable/unstable).

Formal releases are created by creating a Git tag with the desired version number. These tags will trigger automated builds which will release the specified code under that version. Tags can be pushed from a local repository or created through the Gitlab interface: https://gitlab.com/failmap/failmap/tags/new

Informal releases are created by new commits pushed/merged to the master. The version number of the last formal release will be suffixed with the current short Git SHA.

For all releases artifacts will be created. Currently only Docker containers are pushed into the registry. Each artifact will be tagged with the appropriate version (formal or informal). Where needed abstract tags will also be created/updated for these artifacts (eg: Docker build/staging/latest tags).

For local development informal release or a special dev0 build release is used which indicates a different state from the formal releases.

Known Issues

Docker installation

ERROR: for failmap_database_1 Cannot start service database: Mounts denied:

As the error suggests, you’re running the installation from a directory that is not shared with Docker. Change the docker configuration or run the installation from your user directory. You might receive this error if you run docker-composer up from /var/www/ or /srv/www/ as docker by default only has access to your user directory.