Self-host Giga MeterBeta

Backend Setup

There are multiple ways in which you can deploy Giga Meter Backend, providing support for customers who want to implement Giga Meter Backend within their existing infrastructure stack. Let's go through them one-by-one. You can find the instructions for deployment in our README file, which is the section you see when you scroll down in our GitHub repository, or if you've got a copy of Giga Meter Backend downloaded already, you can open the file contained in the downloaded repository called README.md.

License

Giga Meter Backend is licensed under AGPL-3.0 license.

a. Access to Source Code: Users who download and self-host an AGPL v3 project are entitled to the complete corresponding source code of the software. This ensures that they can inspect, modify, and adapt the software to their needs.

b. Network Interaction Clause: AGPL v3 has a unique clause that protects users of networked services. If someone modifies and hosts AGPL software, making it available for others to use (e.g., a web service or SaaS), they must provide access to the modified source code to any user interacting with the software over a network.

c. Freedom to Modify and Share: Once users download and self-host AGPL software, they are free to modify the software and share it with others, if they also distribute the source code and respect the same AGPL license terms. This ensures ongoing user control over the software.

Requirements

Giga Meter Backend runs with pretty minimal hardware requirements by itself. The most intensive part for the software is when you actually build the software, but once it's running it's relatively lightweight.

Giga Meter Backend works with a very large range of operating systems, as it only requires JavaScript execution to run. Giga Meter Backend is known to work well with Windows, Mac, Linux and BSD. Although they do work well on all of them, for production deployments we would suggest Linux as the ideal platform. Any operating system that runs Node.js should be able to work too, but these are some of the common operating systems that we know work well.

To run Giga Meter Backend, you need to install a few things. Node.js, Git, and PostgreSQL. We use Prisma for database maintenance, and is one of the dependencies. We won’t publish installation guides for these as they have their own resources available on the internet.

Development Setup

Clone the repository and install required packages to run locally.

1. First, you git clone the repository with the following command, so you have a copy of the code.

git clone https://github.com/unicef/giga-meter-backend.git

2. Then, go into the directory you just cloned with

cd giga-meter-backend

and run

npm install

Setup Environment Variables

Create an .env file in root folder and add below variables to run locally:

DATABASE_URL: is the url of the database like postgresql://username:password@localhost:5432/pcdc?schema=public.
USE_AUTH: set "true" if APIs should use authentication which uses Giga Maps service API to validate api key generated in Giga Maps generated here. You can check the current auth logic in auth.guard.ts file which calls this endpoint.
PROJECT_CONNECT_SERVICE_URL: Base API URL of the Giga Maps service used for authentication. For Dev, it should be pointed to https://uni-ooi-giga-maps-service-dev.azurewebsites.net
DAILY_CHECK_APP_API_CODE: API code for daily check app used in calling Giga Maps service API. Ideally, it should always DAILY_CHECK_APP but check with the Giga Maps team if this doesn't work.
PCDC_APP_DOWNLOAD_URL: Download URL of the latest version of Giga Meter Windows application.
SENTRY_DSN: To send data to Sentry you will set a client key, usually referred to as the SENTRY_DSN value.

NOTE: PROJECT_CONNECT_SERVICE_URL and DAILY_CHECK_APP_API_CODE values are only required if you want to use in-built Giga Meter authentication and USE_AUTH is set "true" else you can skip them.

DATABASE_URL="database-url" USE_AUTH="true" PROJECT_CONNECT_SERVICE_URL="project-connect-service-url" DAILY_CHECK_APP_API_CODE="daily-check-app-code" PCDC_APP_DOWNLOAD_URL="pcdc-app-download-url" SENTRY_DSN="your-sentry-dsn"

Database Setup

Once the DATABASE_URL is set correctly in the .env file variables, generate prisma client to run the app locally.

1. Run below command inside src/prisma folder to generate prisma client

npx prisma generate

Database Migration

Make the required changes in the prisma.schema file (present inside src/prisma folder).

1. Run below command inside src/prisma folder to migrate database changes

npx prisma migrate dev

Authentication

You can use our default authentication or add your own custom one.

1. To enable authentication, set USE_AUTH="true" in .env file

USE_AUTH="true"

The default auth uses project connect service API to validate a Giga Maps generated api key. You can have a look at the logic here.

2. To use custom auth, you can update the logic in auth.guard.ts file here.

You can refer this NestJS documentation for reference.

Running API server

Once Development Setup, Setup Environment Variables, Database Setup steps are done, you can run the API server locally.

1. Run below command in the root folder

npm run start

The app will run locally on http://localhost:3000/ route.
To open Swagger UI documentation for the API, add /api to the url.
To access all endpoints, add /api/all to the url.

PrevSelf-host GigaMeter

NextBackend Setup via Docker