Setting up Habitica Locally on Docker

Docker
Docker allows development in containers requiring little setup and ensuring a consistent environment for all developers. It also means that you do not need to clutter your host machine with dependencies.

Assistance with these Instructions
The instructions in this Docker section might be outdated or incorrect in parts. If you need help, post to the Aspiring Blacksmiths guild.

If you are familiar with Docker, your assistance in improving these instructions would be most welcome! Here are some points of confusion that contributors have identified:


 * Not entirely clear the difference between the steps: "Use docker-compose to build and start...", "Bootstrap your local clone using...". Are they dependent of each other? Can one step be followed instead of the other? If one step is an optional step, a label that states "optional" may be very helpful. If one step must be followed after the conclusion of another step, then statements like "Go to " at the end of the step may be helpful.
 * Running the command `docker-compose exec web sh` produced error `ERROR: No such service: web`. This has been reproduced by another member of our group who has successfully installed npm while I failed (not sure if that factor is connected to the issue but thought it may be useful to mention).

Initial Docker Setup
Before beginning, follow the instructions for installing docker and docker-compose: https://docs.docker.com/compose/install/.

Verify your installation by clicking the Docker Quickstart Terminal icon on your Desktop (Windows) or Launchpad (Mac OS X).

Follow all the directions in this page before the "Instructions by Operating System" section.

In the Docker Quickstart Terminal, cd to your local habitica folder.

Use docker-compose to build and start both the mongo database and habitica application
The docker-compose.yml file will build a habitica container using the Dockerfile build file and pull the latest mongo image:

This will start three containers in the background. $ docker ps CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES cf95c4331acf       habitica_client     "npm run client:dev"     25 hours ago        Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1 f9bda8e04e9e       habitica_server     "npm start"              25 hours ago        Up 6 seconds        0.0.0.0:3000->3000/tcp             habitica_server_1 17edaab645a4       mongo               "docker-entrypoint.s…"   2 days ago          Up 7 seconds        0.0.0.0:27017->27017/tcp           habitica_mongo_1 Habitica is available on port 3000 and mongo is on port 27017. The version of Habitica running in habitica_client is branch:develop of the Habitica repository.

Note: The application files are stored in an ephemeral container so changes can be easily lost. It is safer and more convenient to mount your local clone of the Habitica repository in the container.

Bootstrap your local clone using the tools already installed in the container.

 * 1) Use  again to stop these containers:


 * 1) Then mount your local clone directory to the habitica_client container and bootstrap:


 * 1) Run the containers using the local clone:

Now changes made to the local clone will be served via the container.

Note: The above step will create another container in your machine. $ docker ps CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES a687e85ac965       habitica_client     "npm run client:dev"     10 minutes ago      Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1 cf95c4331acf       habitica_client     "npm run client:dev"     25 hours ago        Up 5 seconds        3000/tcp, 0.0.0.0:8080->8080/tcp   habitica_client_1 f9bda8e04e9e       habitica_server     "npm start"              25 hours ago        Up 6 seconds        0.0.0.0:3000->3000/tcp             habitica_server_1 17edaab645a4       mongo               "docker-entrypoint.s…"   2 days ago          Up 7 seconds        0.0.0.0:27017->27017/tcp           habitica_mongo_1 This extra container will have random name like elastic_keller and can be removed with docker rm [container_name].

If you experience any errors when running npm commands, check that the correct versions of NodeJS and npm have been installed:

If incorrect versions have been installed, please report it by logging an issue in GitHub so that we can fix the docker configuration. If you are not sure how to install the correct versions, you can ask for help there.

It is important that version 3.4 of MongoDB is used (later versions will give you errors because they don't have the $pushall operator, which is used by Habitica's dependencies). After Pull Request #10270 has been merged, the correct version will be used automatically but until then you must manually ensure that version 3.4 is used. If you need help, ask in the Aspiring Blacksmiths guild.

Running tests in the docker containers
Once you've started the two docker containers with docker-compose, you can attach to the habitrpg_client container for test execution. $ docker-compose exec client sh Now you are in the container, and you can execute test suites using the test commands given in Using Your Local Install to Modify Habitica's Website and API.
 * 1)  <--here's your bash

While creating unit tests, you may also want to run a docker container that only runs tests. $ The command above creates a container called habitica_test, which you can stop and start for running tests.