# 4.1.2 Install OpenCRVS locally {% embed url="" %} The following instructions will guide you on how to set up a local, demo development environment of OpenCRVS using our fictional country configuration: "Farajaland". 1. Check you have installed all the dependencies in the previous section 2. Clone OpenCRVS Core: ```bash git clone git@github.com:opencrvs/opencrvs-core.git ``` 3. Navigate inside the core directory ```bash cd opencrvs-core ``` 4. Ensure that you are on the master branch. The master branch is always aligned to the latest release. Alternatively, checkout a release branch. ```bash git checkout master // or git checkout release-v1.9.0 ``` 5. 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](/setup/3.-installation/3.1-set-up-a-development-environment/3.1.1-install-the-required-dependencies.md) 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: * [Start](/setup/3.-installation/3.1-set-up-a-development-environment/3.1.3-starting-and-stopping-opencrvs.md) OpenCRVS Core * [Start](/setup/3.-installation/3.1-set-up-a-development-environment/3.1.3-starting-and-stopping-opencrvs.md) the OpenCRVS country configuration repository with test data from our fictional country, "Farajaland" and [seed](/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.8-seeding-your-local-database.md) local databases with Farajaland reference data 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/`**](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](/setup/3.-installation/3.1-set-up-a-development-environment/3.1.4-log-in-to-opencrvs-locally.md). * 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: ```bash bash setup.sh ``` {% hint style="danger" %} 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. {% endhint %} If the installation was successful, proceed to the [next section](/setup/3.-installation/3.1-set-up-a-development-environment/3.1.3-starting-and-stopping-opencrvs.md) 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. 1. 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: ```bash cd ../ git clone git@github.com:opencrvs/opencrvs-countryconfig.git ```
2. Inside countryconfig ensure that you are also on the master or an equivalent release branch. ```bash cd opencrvs-countryconfig git checkout master // or git checkout release-v1.9.0 ``` 3. Now prepare some terminal windows like so. In this example, 4 windows are open when running OpenCRVS. Type `nvm use` in 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*](https://ohmyz.sh/) *helps display the correct git branch)*
4. 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. ```bash yarn compose:deps ```
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.
5. 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 ```bash yarn dev --only-dependencies ``` **opencrvs-core (top-right):** This command starts up the core Node microservices locally, outside of docker containers. ```bash yarn dev --only-services ``` {% hint style="info" %} `yarn dev` used on its own, without these parameters, starts up both dependencies and services in the same window. But it can be hard to debug issues with ports if logs for both are combined. {% endhint %} 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)** ```bash yarn dev ```
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. 6. Now that OpenCRVS is running, the opencrvs-core databases must be [seeded](/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.8-seeding-your-local-database.md) with location (administrative structure), test offices and test user data. Inside the **opencrvs-core window (bottom-right)**, run the following [seeding](/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.8-seeding-your-local-database.md) command: ```bash yarn seed:dev ``` The output of successful seeding looks like this:
* Open the url [**`http://localhost:3020/`**](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](/setup/3.-installation/3.1-set-up-a-development-environment/3.1.4-log-in-to-opencrvs-locally.md). * To stop OpenCRVS running, type **ctrl+c** in each of the 3 other windows --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.opencrvs.org/setup/3.-installation/3.1-set-up-a-development-environment/3.1.2-install-opencrvs-locally.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.