First Time Quick Setup¶
This section describes how to set up the system for the first time. It is assumed you are logged into the server machine that you wish to use, using the user account that you want to run the server with. The entire application has been dockerised, so can in theory be used on any major operating system with minimal modification.
Installing required tools¶
You need to have docker
, docker-compose
and git
installed and available on your
command-line.
You can find installation instructions for docker
on all major operating systems
here, and for docker-compose
here. For linux hosts, it is useful to be
able to use docker
as a non-root user, and you can find instructions on how to set
this up here. If you don’t,
note that you will need to add sudo ...
in front of every docker
and
docker-compose
command listed below.
Installation instructions for git
for all major OSs can be found
here.
Get the galv source code¶
First you will need to clone the galv repository using git
:
git clone https://github.com/Battery-Intelligence-Lab/galv.git
cd galv
Setup environment variables¶
The Galv project uses two .env
files, .env
and .env.secret
.
You will already have a .env
file in the repository you cloned, with sensible defaults.
If you’re running a production deployment, you will want to set the value of the
VIRTUAL_HOST_ROOT
to your domain name, e.g. VIRTUAL_HOST_ROOT=example.com
.
This will serve the Galv web application from the root of your domain,
e.g. at http://example.com/
; and the API from the subdomain, e.g. http://api.example.com
.
You will likely also want to enable HTTPS, for which we use LetsEncrypt to generate SSL certificates.
By default, the staging (test) server is used, which generates certificates that are not trusted by browsers.
When your production setup appears to work correctly, you can switch to fetching real certificates
by setting LETSENCRYPT_TEST=false
and restarting the nginx-proxy container.
If you wish to change where the database is saved, you can change the first entry
in .env
, GALV_DATA_PATH
to the directory where you want the postgres database.
Create .env.secret
¶
The second .env
file is a secrets file.
This is not included because you should come up with your own secret values for the
entries within it.
Create the file and edit it so that it has the following keys:
DJANGO_SECRET_KEY
DJANGO_SUPERUSER_PASSWORD
POSTGRES_PASSWORD
All of these values should be unguessable secure passwords. DJANGO_SECRET_KEY should be very long and complex, consider 60+ characters with a mixture of special characters (avoid $), upper- and lower-case letters, and numbers. The only one of these you will need to use again will be the superuser password.
If you would like the Django superuser to have a name that is not ‘admin’, you can also specify DJANGO_SUPERUSER_USERNAME.
vi .env.secret # could also use nano, emacs, etc.
Build docker images (only when upgrading to a new version of galv)¶
If you have previously installed and run galv you might already have old docker images already built. To rebuild the images, run the following command:
docker-compose build
Running Galv¶
You can run the galv server and web application frontend using the following
docker-compose
command from the root folder of the repository.
docker-compose up
Now view the ‘localhost’ IP address http://127.0.0.1/ in your browser and you should see the Galv login page. This is the web frontend. If you wish to use the frontend from another machine, use the IP address or URL of the server instead.
Creating a user account¶
It’s not a good idea to do everything with the Django superuser, so create a new account on the login page. You’ll see that you get a message telling you that the account needs to be approved by an existing account.
Refresh the page, and login using the _superuser_ credentials.
Once logged in, go to the bottom tab in the menu (Approve Users), and click the button next to your new user account
Now, click the logout button in the top right, and log back in with your new user account
Setting up a Harvester¶
Harvesters are set up using a part of the code of the main Galv repository. The first step, then, is to log onto the machine that will run the harvesters and clone the repository again. If you are using the same server for the harvester and the rest of Galv, you can skip this step.
git clone https://gitlab.com/battery-intelligence-lab/galv-project/galv.git
cd galv
Next, launch the harvester container, specifying the Harvester’s docker-compose configuration file:
docker-compose -f docker-compose.harvester.yml run harvester bash
python start.py
This will launch into an interactive shell which will guide you through the Harvester setup process.
First, you’ll be asked for the Galv server URL.
If you’re running on the same server as the Galv server, this will be http://app
,
otherwise it will be the path you entered above to connect to the web frontend,
but using the api
subdomain. So if you went to http://example.com
, go to http://api.example.com
.
Next, you’ll be asked to specify a name for the new Harvester.
Each Harvester needs at least one administrator. You’ll be given a list of (approved) user accounts, and will select one to be the Harvester administrator. If you’re following this guide, you’ll see the Django superuser account and the regular user account you just created. Select the regular user account. You can add other administrators and users to the Harvester using the web frontend later.
When an administrator has been selected the Harvester will register itself with the Galv server and begin to monitor for data files. Of course, it currently has no directories to monitor, so the last step is to go to the web frontend and configure at least one monitored path for the Harvester.
Open up the web frontend in a browser, log in as the Harvester administrator user, and select the ‘Harvesters’ tab. Click on the magnifying glass icon to see details for your new Harvester. Enter a path for the Harvester to monitor (relative to the Harvester’s system), and click the plus icon to save your new path.
The Harvester will now crawl the directory, observing files and importing them when they have been stable for a sufficiently long time.
Maintenance¶
To run the server in detached mode (i.e. run containers in the background) using the
-d
option
docker-compose up -d
To start the server side system again after it has been stopped simply run
docker-compose up
in the root folder.
A template SystemD service file is included in the repository root directory
galv.service
that can be used to automatically start the system on Linux servers.
If Harvesters go down, they can be restarted. .. code-block:: shell
docker-compose -f docker-compose.harvester.yml run harvester python start.py –restart