Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG is the official Singapore government link shortener. This project provides a unified codebase for three distinct environments: go.gov.sg, for.edu.sg, and for.sg. The system allows authorized public officers, education officers, and healthcare professionals to create recognizable and authenticated short links for citizens. Sources: README.md:16-30
The local setup environment enables developers to run the full stack, including the React frontend and Node.js/Express backend, using Docker containers for infrastructure dependencies like PostgreSQL and Redis. Sources: README.md:46-59
Prerequisites
You must install the following software versions before starting the setup:
- Node.js: version 18 (Note:
package.jsonspecifies engines compatibility up to version 24). - pnpm: version 12.0.0.
- Docker: version >= 18.09.0.
- docker-compose: version >= 1.23.1.
- Rosetta (for Apple Silicon Macs): Required for
docker-compose@v1compatibility.
Sources: README.md:37-43, package.json:8
Initial Installation
- Clone the repository:
git clone git@github.com:opengovsg/GoGovSG.git gogovsg. - Navigate to the directory:
cd gogovsg. - Install dependencies:
pnpm install.
Sources: README.md:46-55
Local Development Workflow
The project uses concurrently to manage the simultaneous execution of the frontend development server and the backend API server. Sources: README.md:214-219
Running with Docker Compose
You can start the entire local environment, including a PostgreSQL database and Redis container, with a single command:
pnpm run dev
This command executes docker compose -f docker-compose.yml up --build. Once complete, the application is accessible at http://localhost:3000. Sources: README.md:58-61, package.json:20
Local Networking and Proxies
The development environment utilizes a proxy system to handle frontend and backend communication:
- Webpack Dev Server: Listens on port
3000. - Backend Server: Listens on port
8080. - API Proxy: Requests sent to
localhost:3000/apiare proxied tolocalhost:8080/api. - Redirect Proxy: Shortlinks accessed via
localhost:3000/shortlinkare proxied to the backend atlocalhost:8080/shortlink. - Maildev: Captures One-Time Passwords (OTPs) for local login at
http://localhost:1080/.
Sources: README.md:62-68, webpack.config.ts:145-156
Component Architecture
The following diagram illustrates the interaction between local development components:
The diagram shows the request flow from the browser through the Webpack proxy to the backend services and databases.
Sources: README.md:58-75, webpack.config.ts:145-156
Configuration and Environment Variables
The server requires several environment variables for infrastructure connectivity. In development, the NODE_ENV is set to development, which disables certain security restrictions like mandatory HTTPS for cookies. Sources: src/server/config.ts:107-113
Core Infrastructure Variables
| Variable | Description | Example |
|---|---|---|
DB_URI | PostgreSQL connection string | postgres://postgres:postgres@postgres:5432/postgres |
REDIS_OTP_URI | Redis for OTP storage | redis://redis:6379/0 |
REDIS_SESSION_URI | Redis for browser sessions | redis://redis:6379/1 |
OG_URL | The origin URL for the site | https://go.gov.sg |
SESSION_SECRET | Secret for hashing sessions | change-this |
VALID_EMAIL_GLOB_EXPRESSION | Allowed user email pattern | *@youremaildomain.com |
Sources: README.md:82-105, src/server/config.ts:25-40
Build Pipeline
The project uses TypeScript and Webpack to bundle assets. The ASSET_VARIANT variable determines which environment assets (gov, edu, or health) are included in the build. Sources: webpack.config.ts:11-53
The build process transforms TypeScript and variant-specific assets into a production-ready distribution folder.
Sources: package.json:16-17, webpack.config.ts:60-143
Development Tools
- Linter:
oxlintis used for identifying patterns in JS/TS. Run viapnpm run lint. - Formatter:
oxfmthandles code formatting. Run viapnpm run format. - Server Watcher:
tsx watch(formerlyts-node-dev) monitors server changes and restarts automatically. - Debugging: The server supports the Node.js Inspector protocol on port
9229.
Sources: README.md:183-195, package.json:10-13, package.json:19
Contributing Guidelines
When contributing to GoGovSG, you must follow the established pull request process:
- Discuss changes via an Issue before implementation.
- Submit a Contributor License Agreement (CLA) at go.gov.sg/ogp-cla.
- Update the
README.mdif your changes introduce new environment variables or interface changes. - Ensure two developers sign off on the pull request before merging.
Sources: CONTRIBUTING.md:11-20, CONTRIBUTING.md:41-55
This setup provides a robust environment for developing the Singapore government's trusted link shortener, ensuring that all local tests and infrastructure mimics the multi-tenant production environment.