Giga is a UNICEF-ITU global initiative to connect every school to the Internet and every young person to information, opportunity, and choice. By connecting all schools to the Internet, we ensure that every child has a fair shot at success in an increasingly digital world.
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.- Node Package Manager (npm)
- Node.js 20+
- PostgreSQL DB v15+
Clone the repository and install required packages to run locally.
- 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
- Then, go into the directory you just cloned with
cd giga-meter-backend
and run
npm install
Create an .env file in root folder and add below variables to run locally:
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"
NODE_ENV="ENVIRONMENT"- 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.
- NODE_ENV: The application environment, should be "development" or "production"
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.
Once the DATABASE_URL is set correctly in the .env file variables, generate prisma client to run the app locally.
- Run below command inside src/prisma folder to generate prisma client
npx prisma generate
Make the required changes in the prisma.schema file (present inside src/prisma folder).
- Run below command inside src/prisma folder to migrate database changes
npx prisma migrate dev
You can use our default authentication or add your own custom one.
- 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.
- To use custom auth, you can update the logic in auth.guard.ts file here. You can refer this NestJS documentation for reference.
Once Development Setup, Setup Environment Variables, Database Setup steps are done, you can run the API server locally.
- 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.
You can run unit tests and check the code coverage after setting up the app locally. Run tests and coverage
- Run unit tests
npm run test
- Check test coverage
npm run test:cov
The Minimum Infrastructure requirements to self-host Giga Meter Backend is mentioned below:
1. Application Server:
- CPU: 2-4 vCPUs
- RAM: 4-8 GB
- Storage: 20-40 GB SSD
- OS: Ubuntu 18.04 is the minimum, it's recommended to use a more recent version (e.g., Ubuntu 22.04) for better performance, security, and access to the latest features.
2. Database Server (PostgreSQL):
- CPU: 2-4 vCPUs
- RAM: 4-8 GB
- Storage: 50-100 GB SSD
- OS: Ubuntu 18.04 is the minimum, it's recommended to use a more recent version (e.g., Ubuntu 22.04) for better performance, security, and access to the latest features.
3. Networking:
- Restrict access to necessary ports
- HTTPS for secure communication
4. Software Requirements::
- Node.js (20 or later)
- PostgreSQL (15 or later)
The Docker configuration for Giga Meter is an effort powered by people within the community. Giga Meter does not provide official support for Docker, but we will accept fixes and documentation. Use at your own risk.
Make sure you have docker & docker compose installed on the server or system.
Note: docker compose without the hyphen is now the primary method of using docker-compose, per the Docker documentation.
We have added a docker file which can be used to create an image and deploy the app in your infrastructure. You can have a look at the file here.
Building docker image is quite straight forward and can be done using the following command
docker build -f Dockerfile -t repo:tag
The application is running on port 3000. The following command runs the docker container on port 3000
docker run -d -p 3000:3000 -e
DAILY_CHECK_APP_API_CODE=DAILY_CHECK_APP -e
DATABASE_URL=YOUR_POSTGRES_DATABASE_CONNECTION_STRING -e
PCDC_APP_DOWNLOAD_URL=PCDC_APP_DOWNLOAD_URL -e
PROJECT_CONNECT_SERVICE_URL=PROJECT_CONNECT_SERVICE_URL -e
USE_AUTH=true_or_false image_repo:tag
At Giga, we're committed to maintaining an environment that's respectful, inclusive, and harassment-free for everyone involved in our project and community. We welcome contributors and participants from diverse backgrounds and pledge to uphold the standards.
Click here for detailed Code of Conduct
Thank you for considering contributing to Giga Meter Backend! We value your input and aim to make the contribution process as accessible and transparent as possible. Whether you're interested in reporting bugs, discussing code, submitting fixes, proposing features, becoming a maintainer, or engaging with the GigaMeter community, we welcome your involvement.
Click here for detailed Contribution Guidelines
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. See LICENSE for more information.
For the plain text version please see https://www.gnu.org/licenses/agpl-3.0.txt
GigaMeter Project Lead: Shilpa Arora: [email protected]
GigaMeter Project Member: Vipul Bhavsar: [email protected]
Giga Open-Source Community Manager: David Njagah: [email protected]
Giga Website: https://giga.global/contact-us/
- Thanks to Nagarro for helping build this application!