Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 20+
Docker and Docker Compose
Git
PostgreSQL (local or cloud)

For production deployments, you’ll also need AWS CLI configured with appropriate credentials, kubectl, and Terraform installed.

Installation

Clone the Repository

Clone the GovTech Multicloud Platform repository:

git clone https://github.com/alexander-fq/multicloud.git
cd multicloud/platform

The repository contains two main directories:

platform/ - Complete demo with running application
skeleton/ - Template for new projects

Start with Docker Compose

The fastest way to get started is using Docker Compose:

docker-compose up -d

This will start:

PostgreSQL on port 5432
Backend API on port 3000
Frontend on port 80

What's happening behind the scenes?

Docker Compose launches three containers:

postgres - PostgreSQL 15 Alpine with health checks
backend - Node.js Express API with hot reload
frontend - React SPA served by Nginx with API proxy

All containers are connected via the govtech-network bridge network.

Verify the Installation

Check that all services are healthy:

# Check container status
docker-compose ps

# Test backend health
curl http://localhost:3000/api/health

# Test database health
curl http://localhost:3000/api/health/database

# Test cloud credentials
curl http://localhost:3000/api/health/cloud

Expected response from /api/health:

{
  "status": "healthy",
  "timestamp": "2026-03-03T18:30:00.000Z",
  "provider": "aws",
  "uptime": 45.2,
  "checks": {
    "database": {
      "status": "healthy",
      "stats": { "total": 10, "idle": 4, "waiting": 0 }
    },
    "cloudCredentials": { "status": "healthy" }
  },
  "responseTime": "5ms"
}

Access the Platform

Open your browser and navigate to:

Frontend: http://localhost
Backend API: http://localhost:3000
API Docs: http://localhost:3000/api/health

You should see the GovTech platform homepage with current provider information and key statistics.

Manual Setup (Without Docker)

If you prefer to run services individually:

Setup PostgreSQL

Install and start PostgreSQL:

# On Ubuntu/Debian
sudo apt-get install postgresql-15
sudo systemctl start postgresql

# Create database
sudo -u postgres createdb govtech_dev

Configure Backend

Navigate to the backend directory and install dependencies:

cd platform/app/backend
npm install

Create .env file from the example:

cp .env.example .env

Edit .env with your configuration:

.env

# General
NODE_ENV=development
PORT=3000
HOST=0.0.0.0

# Cloud Provider Selection
CLOUD_PROVIDER=aws

# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_BUCKET=govtech-documents
AWS_LOG_GROUP=/aws/govtech/api

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/govtech_dev

# Security
JWT_SECRET=your-jwt-secret-key-change-this-in-production
API_RATE_LIMIT=100

Never commit .env files to version control. The .env.example file is provided as a template.

Start Backend

npm start

For development with auto-reload:

npm run dev

The backend will be available at http://localhost:3000

Setup Frontend

In a new terminal, navigate to the frontend directory:

cd platform/app/frontend
npm install
npm run dev

The frontend will be available at http://localhost:5173

Environment Variables

General Configuration

Variable	Default	Description
`NODE_ENV`	development	Environment mode
`PORT`	3000	Backend server port
`HOST`	0.0.0.0	Server bind address

Cloud Provider

Variable	Options	Description
`CLOUD_PROVIDER`	aws, oci, gcp, azure	Active cloud provider

AWS Configuration

Variable	Example	Description
`AWS_REGION`	us-east-1	AWS region
`AWS_ACCESS_KEY_ID`	AKIA…	AWS access key
`AWS_SECRET_ACCESS_KEY`	secret…	AWS secret key
`AWS_BUCKET`	govtech-documents	S3 bucket name
`AWS_LOG_GROUP`	/aws/govtech/api	CloudWatch log group

Database

Variable	Example	Description
`DATABASE_URL`	postgresql://user:pass@host:5432/db	PostgreSQL connection string

Security

Variable	Default	Description
`JWT_SECRET`	-	JWT signing key (min 32 chars)
`API_RATE_LIMIT`	100	Requests per 15 minutes

Available Scripts

Backend Commands

cd app/backend
npm start

Frontend Commands

cd app/frontend
npm run dev  # Port 5173

Docker Commands

docker-compose up -d

Testing the API

Health Endpoints
Platform Info
Migration Tools

# Overall health
curl http://localhost:3000/api/health

# Database health
curl http://localhost:3000/api/health/database

# Cloud credentials
curl http://localhost:3000/api/health/cloud

# Basic platform info
curl http://localhost:3000/

# Detailed info
curl http://localhost:3000/api/info

# Current provider
curl http://localhost:3000/api/info/provider

# Architecture patterns
curl http://localhost:3000/api/info/architecture

# Scan current infrastructure
curl -X POST http://localhost:3000/api/migration/scan

# Create migration plan
curl -X POST http://localhost:3000/api/migration/plan \
  -H "Content-Type: application/json" \
  -d '{"from":"aws","to":"oci"}'

# List supported providers
curl http://localhost:3000/api/migration/providers

Troubleshooting

Server won't start

Symptoms: Backend fails to start or exits immediatelySolutions:

Check if port 3000 is already in use:
```
lsof -i :3000
```
Verify DATABASE_URL is correct in .env
Ensure PostgreSQL is running:
```
docker-compose ps postgres
```
Check backend logs:
```
docker-compose logs backend
```

Database connection failed

Symptoms: “ECONNREFUSED” or “Connection timeout” errorsSolutions:

Verify PostgreSQL is running:
```
docker-compose ps postgres
```

Check connection string format in .env:

DATABASE_URL=postgresql://username:password@hostname:5432/database_name

Test connection manually:

psql postgresql://postgres:postgres@localhost:5432/govtech_dev

Wait for PostgreSQL to be fully ready (check health):

docker-compose exec postgres pg_isready -U postgres

AWS credentials invalid

Symptoms: Cloud health check fails or AWS operations errorSolutions:

Verify credentials in .env are correct
Test AWS CLI access:
```
aws sts get-caller-identity
```
For local development, you can use placeholder credentials (demo mode)
Ensure IAM user has necessary permissions (S3, CloudWatch, RDS)

Docker build fails

Symptoms: Image build errors or dependency installation failsSolutions:

Clear Docker cache:
```
docker-compose build --no-cache
```
Remove old images:
```
docker system prune -a
```
Check Dockerfile syntax in app/backend/Dockerfile
Ensure package.json has valid dependencies

Next Steps

Platform Overview

Learn about the architecture and multi-cloud design patterns

Deploy to Kubernetes

Deploy to EKS, GKE, or AKS with Terraform

API Reference

Explore all available endpoints

Migration Guide

Learn how to migrate between cloud providers

You now have the GovTech Multicloud Platform running locally! Explore the platform features and check out the platform overview to understand the architecture.

Get Started

Architecture

Deployment

Multi-Cloud

Security

Operations

Prerequisites

Installation

Manual Setup (Without Docker)

Environment Variables

Available Scripts

Backend Commands

Frontend Commands

Docker Commands

Testing the API

Troubleshooting

Next Steps

Platform Overview

Deploy to Kubernetes

API Reference

Migration Guide

Build docs developers (and LLMs) love

Get Started

Architecture

Deployment

Multi-Cloud

Security

Operations

​Prerequisites

​Installation

​Manual Setup (Without Docker)

​Environment Variables

​Available Scripts

​Backend Commands

​Frontend Commands

​Docker Commands

​Testing the API

​Troubleshooting

​Next Steps

Platform Overview

Deploy to Kubernetes

API Reference

Migration Guide

Build docs developers (and LLMs) love

Prerequisites

Installation

Manual Setup (Without Docker)

Environment Variables

Available Scripts

Backend Commands

Frontend Commands

Docker Commands

Testing the API

Troubleshooting

Next Steps