GovQueue Local Deployment Instructions

Byteheads - TechTriathlon 2025

Prerequisites

  • Docker and Docker Compose: Ensure Docker and Docker Compose are installed and running on your system.
  • Node.js: Node.js version 20 or higher is required (Required for expo).
  • ADB (Android Debug Bridge): Required for connecting to an Android device. This is typically included with Android Studio.
  • Git: Required for cloning the repositories.

1. Backend Deployment

The backend is a containerized application that runs using Docker Compose.

Clone the repository:

git clone https://github.com/Techtriathlon-25-Byteheads/backend.git
cd backend

Bring up the backend services: From the root of the backend repository, run the following command. This will build the Docker images and start the containers. The superuser credentials will be automatically seeded into the database.

email : superadmin@gov.lk password : password123

docker compose up -d --build

Troubleshooting: OpenSSL/Prisma Error

If you encounter an error message during the build process similar to this:

prisma:warn Prisma failed to detect the libssl/openssl version to use, and may not work as expected. Defaulting to "openssl-1.1.x".
Please manually install OpenSSL and try installing Prisma again.

You need to manually add the OpenSSL package to the Docker image.

  1. Open the Dockerfile located in the root of the backend repository.

  2. Add the following lines just before the RUN npm install command:

    # Install OpenSSL for Prisma
RUN apk update && apk upgrade
RUN apk add --no-cache openssl

  3. Save the Dockerfile and run the build command again:

    docker compose up -d --build

2. Cloudflare Tunnel Setup

To expose your local backend service to the internet for mobile app testing, you can use a Cloudflare Tunnel. This will create a secure connection from a public Cloudflare URL to your local machine. ** Please note that the expo app is supposed to be run on mobile and some of the implementation like local storage wont work and the app will break if its run as a web app instead. **

1. Install cloudflared: Follow the official Cloudflare installation guide for your operating system.

2. Start the Tunnel: Run the following command in your terminal. This will start a tunnel and connect it to your local backend server running on port 3000. The --protocol http2 flag is used to ensure a stable connection over TCP, avoiding potential issues with the default QUIC (UDP) protocol.

The app uses WebSockets for real time queue updates, and we had issues with QUIC and socket io.

cloudflared tunnel --url http://localhost:3000 --protocol http2

3. Get Your Public URL: Once the tunnel starts, cloudflared will output a public URL (e.g., https://random-words.trycloudflare.com). Copy this URL, as you will need it to configure the mobile application.

3. Mobile App (Client Frontend)

The mobile app is built with Expo.

1. Clone the repository:

git clone https://github.com/Techtriathlon-25-Byteheads/client-app-frontend.git
cd client-app-frontend

2. Install dependencies:

npm install

3. Configure the API Endpoint:

  • Open the file services/api.ts.

  • Locate the baseURL variable and change its value to the public URL you obtained from the Cloudflare Tunnel. Make sure to append /api to the end of the URL.

    // services/api.ts
const  BASE_URL  =  'https://your-cloudflare-tunnel-url.trycloudflare.com/api';

  • Open the file services/socket.ts.

  • Locate the baseURL variable and change its value to the public URL you obtained from the Cloudflare Tunnel. Here don't append /api.

    // services/socket.ts
const  SOCKET_URL  =  'https://your-cloudflare-tunnel-url.trycloudflare.com';

4. Prepare Your Android Device: To run the app on a physical Android device, you need to enable developer options and USB debugging.

  • On your Android device, go to Settings > About phone.
  • Tap on Build number seven times to enable developer options.
  • Go back to the main Settings menu, find Developer options.
  • Inside Developer options, enable USB debugging.
  • Connect your device to your computer via a USB cable.
  • When prompted on your device, allow USB debugging from your computer.

5. Run the Application: To build and run the app directly on your connected Android device, execute the following command from the root of the client-app-frontend directory.

npx expo run:android

This command will install the app and its dependencies on your device and launch it. If you have multiple devices connected, you may be prompted to choose one.

Alternatively, you can start the development server:

npx expo start

After the Metro bundler starts, press a in the terminal to attempt to open the app on a connected Android device.

4. Admin Portal (Admin Dashboard)

The admin portal is a separate frontend application.

1. Clone the repository:

git clone https://github.com/Techtriathlon-25-Byteheads/admin-dashboard-frontend.git
cd admin-dashboard-frontend

2. Install dependencies:

npm i

(Note: npm i is a shorthand for npm install)

3. Start the development server:

npm start

This will launch the admin portal, typically available at http://localhost:5173 in your web browser.

AI Agent (RAG)

Unfortunately we did not have enough time to fully integrate the AI with the app. However the actual RAG and the Vector database as well as the WebSocket API is fully built and can be found in the RAG-agent repo.