Following this documentation allows you to set up a locally running Arkindex instance (Community Edition) for development, where you can make any changes to the code and immediately see how they affect the backend Rest API and frontend display.
This setup is NOT suitable for production use. To find out how to deploy Arkindex to production (using Docker images), you should refer to the deployment documentation.
We recommend you use a Linux distribution such as Debian or Ubuntu to follow these instructions. We at Teklia exclusively use Ubuntu LTS 22.04.
Minimal software requirements are:
sudo apt install binutils libproj-dev gdal-binIn order to set up your local Arkindex instance, you first need to clone two projects: Arkindex backend and frontend.
You should clone them in the same parent folder, as some commands will assume specific relative paths.
You can clone the repositories anonymously using HTTPS clone:
git clone https://gitlab.teklia.com/arkindex/backend.git
git clone https://gitlab.teklia.com/arkindex/frontend.git
If you want to contribute to Arkindex and submit patches, we recommend you use SSH cloning. To do so, you need to create an account on our own Gitlab instance at gitlab.teklia.com.
In order to use SSH cloning, you need:
You can find more information here on how-to setup an SSH key for git access.
Once you are connected to gitlab.teklia.com, you need to add your SSH public key to your user account on Teklia's GitLab instance. To do so, you can follow the official GitLab instructions.
To gain and keep access to Arkindex's GitLab repositories as a contributor, your GitLab account must be protected with Multiple Factor Authentication (generally using one time passwords generated from your phone).
You will need to setup an app like Google Authenticator or Duo Mobile on your phone, and then follow these steps.
If you do not complete the 2FA initial activation within 72 hours of creating your account, it will be automatically disabled.
Finally you can clone the projects:
git clone git@gitlab.teklia.com:arkindex/backend.git
git clone git@gitlab.teklia.com:arkindex/frontend.git
Arkindex relies on several third-party open-source services to store data and communicate across components:
All these services run through docker, and are configured in a docker-compose.yml file stored in the backend repository.
A convenient Makefile shortcut is available to start all these services in a dedicated shell:
cd backend
make services
You should see a few services start and log their output in the shell.
On a first start, mkcert will generate a Certificate Authority for your instance so that it's only one exposed using HTTPS.
In order to setup the Arkindex backend, you must first (in a different terminal than the one where the services are running) create a Python virtual environment and populate it:
cd backend
mkvirtualenv -a $(pwd) -p /usr/bin/python3.10 arkindex
pip install -e .
Next you need to configure your Arkindex instance, by copying the sample config file to the expected path:
cp config.yml.sample arkindex/config.yml
Later on, you'll be able to edit arkindex/config.yml to further configure your Arkindex instance.
After a few moment of Python dependencies installation, you should be able to run commands using the arkindex script.
First, you need to build the initial empty database structure:
arkindex migrate
Then populate it with some common settings for developers:
arkindex bootstrap
And create your own administrator account:
arkindex createsuperuser
Finally, you can run the development webserver:
arkindex runserver
You should be able to login on the admin portal through http://localhost:8000/admin/
The frontend installation only requires npm:
cd frontend
npm install
From there, you can run the development server:
npm run start
And access the whole interface at http://localhost:8080
The backend and services must be running while using the frontend interface, otherwise all you'll get is a "server unreachable" error page.