4.1.2 Install OpenCRVS locally
The following instructions will guide you on how to set up a local, demo development environment of OpenCRVS using our fictional country configuration: "Farajaland".
Check you have installed all the dependencies in the previous section
Clone OpenCRVS Core:
Navigate inside the core directory
Ensure that you are on the master branch. The master branch is always aligned to the latest release. Alternatively, checkout a release branch.
Run the optional installer command explained below, or alternatively proceed to Manual installation explained below if you encounter issues.
This installer script is quite opinionated regarding your setup and may fail depending on your permissions. Depending on your laptop, you may prefer a manual setup process.
This installer script will use tmux to:
Test that your dependencies are installed correctly
Checks that required ports are available. Note: MacOS runs AirPlay on port 5000. Mac users need to disable AirPlay in System Preferences in order to run OpenCRVS.
Download and install all Docker images
Check out the example OpenCRVS country configuration repository in a directory alongside opencrvs-core: https://github.com/opencrvs/opencrvs-countryconfig
Start OpenCRVS Core
If there are any missing dependencies the script will exit and display instructions. Once the dependency is satisfied, you can try again.
On completion you will see the OpenCRVS logo
Open the url
http://localhost:3020/You have successfully installed a local OpenCRVS development environment on your laptop! 🎉
Proceed to login using the details in the section 3.14 Log in to OpenCRVS.
To stop OpenCRVS running in the installer, type ctrl+c, then exit in each tmux terminal window
To run the installer script, use this command:
Do not use sudo bash setup.sh!
The bash setup.sh command needs to set folder permissions for Elasticsearch and Docker. If you use sudo, the owner of the /data folder becomes root. You will encounter permissions problems that are hard to debug.
If the installation was successful, proceed to the next section for further learning about safely starting and stopping OpenCRVS. Otherwise, if you encountered issues, continue with the manual apprach below:
Manual installation locally
If you are not using the script above, or encounter issues with it, proceeding manually is the best bet to incrementally solve local issues on your laptop.
Navigate outside of opencrvs-core and clone OpenCRVS Countryconfig in a directory alongside your clone of opencrvs-core so that you have in a parent directory, both opencrvs-core and opencrvs-countryconfig:
Inside countryconfig ensure that you are also on the master or an equivalent release branch.
Now prepare some terminal windows like so. In this example, 4 windows are open when running OpenCRVS. Type
nvm usein each window to ensure you are running the correct node version.
Notice that 3 windows are navigated inside the opencrvs-core directory, and one (bottom-left) is in the opencrvs-countryconfig directory. (The tool oh-my-zsh helps display the correct git branch)
Ensure Docker Desktop is running, and in the opencrvs-core window in the top right, run the following command to download and run Docker images containing the database dependencies.
This will fail if Docker installation has failed.
Once all the dependencies are downloaded and started, if you run docker ps in another window you can check that all have started up successfully. You will have to debug dependency and port problems yourself if any container is not starting. Refer to any error messages you see, unique to your laptop and internet resources to help you. With the exception of opencrvs/hearth, these dependencies are outside the scope of OpenCRVS.
Run Ctrl+C twice in the opencrvs-core window in the top right, to quit all docker containers. Run docker ps to ensure all have stopped. If any are still running, you will have to force stop all docker containers before continuing.
Run the following commands in the appropriate windows to start up OpenCRVS:
opencrvs-core (top-left):
This command starts up the same dependencies as above
opencrvs-core (top-right):
This command starts up the core Node microservices locally, outside of docker containers.
You will be asked to confirm that you are ready to start a country configuration server alongside opencrvs-core. Click Y to continue.
opencrvs-countryconfig (bottom-left)
A successful start up looks like this:
opencrvs-countryconfig expects opencrvs-core auth service and dependencies to be running. Then opencrvs-core runs data migrations using data from opencrvs-countryconfig. Any port issues need to be debugged independently. If for any reason the events microservice has not started, following tasks will fail. You can save any TypeScript file in opencrvs-core/packages/events/src to force a restart of events.
When opencrvs-countryconfig starts up, it seeds a PostgreSQL database schema: "analytics" within the "events" database with location (administrative hierarchy) information related to your country. This configurable database is used for business intelligence dashboards.
The output of successful seeding looks like this:
Open the url
http://localhost:3020/You have successfully installed a local OpenCRVS development environment on your laptop! 🎉
Proceed to login using the details in the section 3.14 Log in to OpenCRVS.
To stop OpenCRVS running, type ctrl+c in each of the 3 other windows
Last updated