--- title: "Local Setup" description: "Local development setup with PostgreSQL 16, PostGIS, Auth.js v5, and Ring Platform service layer" locale: "en" --- # Local Development Setup Guide to setting up Ring Platform for local development. ### For founders ## What You Need - Node.js 22, pnpm/npm, and Git installed on your machine - PostgreSQL 16 + PostGIS (via Homebrew, Docker, or native install) - A code editor (VS Code recommended) ## Setup Overview 1. Clone the repository 2. Install dependencies 3. Configure environment variables from `env.local.template` 4. Set up PostgreSQL and run migrations 5. Start the development server ### For developers ## Prerequisites ### Required Software - **Node.js 22** — [Download from nodejs.org](https://nodejs.org/) - **npm 10+** or **pnpm 9+** — Package manager - **Git** — Version control - **PostgreSQL 16** with **PostGIS** extension — See database setup section - **VS Code** — Recommended IDE ### Optional Tools - **Docker** — For containerized PostgreSQL (alternative to Homebrew install) - **Postman** or **Bruno** — API testing ## Installation ### 1. Clone the Repository {`git clone https://github.com/connectplatform/ring.git cd ring`} ### 2. Install Dependencies {`npm install`} {`pnpm install`} ### 3. Environment Configuration Copy the environment template: {`cp env.local.template .env.local`} > **Warning** > The `DB_BACKEND_MODE` variable is **required** — the platform will not start without it. For local development with PostgreSQL, set it to `k8s-postgres-fcm`. Configure your `.env.local` file with these essential variables: {`# Database backend mode (REQUIRED) DB_BACKEND_MODE=k8s-postgres-fcm # PostgreSQL connection DB_HOST=localhost DB_PORT=5432 DB_NAME=ring_platform DB_USER=ring_user DB_PASSWORD=ring_password_2024 DATABASE_URL=postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform # Auth.js v5 AUTH_SECRET=generate-a-random-secret-here AUTH_TRUST_HOST=true AUTH_GOOGLE_ID=your_google_client_id AUTH_GOOGLE_SECRET=your_google_client_secret # Application NEXT_PUBLIC_BASE_URL=http://localhost:3000 NODE_ENV=development`} > **Tip** > Generate `AUTH_SECRET` with: `npx @better-auth/cli secret` See [Environment Configuration](/docs/en/deployment/environment.md) for the full list of supported variables and their descriptions. ### 4. Database Setup #### Option A: Docker (Recommended for local dev) {`# Start PostgreSQL 16 with PostGIS docker run -d \\ --name ring-postgres-dev \\ -e POSTGRES_USER=ring_user \\ -e POSTGRES_PASSWORD=ring_password_2024 \\ -e POSTGRES_DB=ring_platform \\ -p 5432:5432 \\ postgis/postgis:16-3.4`} #### Option B: Homebrew (macOS) {`brew install postgresql@16 postgis brew services start postgresql@16 # Create the database user and database createuser ring_user -P # password: ring_password_2024 createdb ring_platform -O ring_user`} > **Info** > For multi-clone local development, use the bootstrap script at `infrastructure/postgres/bootstrap-brew-dev.sh`. See `infrastructure/postgres/MIGRATION-KINGDOM-MATRIX.md`. #### Run Migrations {`npm run db:migrate`} > **Tip** > Migration files live in `data/` directory. The migration runner reads `DB_BACKEND_MODE` to select the correct adapter. For local PostgreSQL (`k8s-postgres-fcm`), it applies SQL migrations from `data/schema.sql` and `data/migrations/`. ### 5. Start Development Server {`npm run dev`} The application will be available at: - **Frontend**: http://localhost:3000 - **API Routes**: http://localhost:3000/api/* - **Health Check**: http://localhost:3000/api/health ## Development Tools ### Hot Reload The Next.js development server supports hot reload for: - React components and Server Components - API routes - Tailwind CSS changes - Locale files (requires server restart for new keys) ### Type Checking {`npm run type-check`} ### Linting {`npm run lint`} ## Project Structure ``` ring-platform.org/ ├── app/ # Next.js 16 App Router │ ├── (auth)/ # Auth pages (login, register) │ ├── api/ # API routes │ └── (public)/ # Public pages ├── features/ # Feature modules │ ├── news/ # News management │ ├── entities/ # Entity management │ ├── opportunities/ # Opportunity system │ └── wallet/ # Web3 wallet ├── lib/ # Core libraries │ ├── database/ # Database abstraction │ │ ├── DatabaseService.ts │ │ └── adapters/ # PostgreSQLAdapter, FirebaseAdapter │ ├── firebase-admin.server.ts # Firebase Admin (FCM only) │ └── auth-adapter-singleton.ts # Auth.js adapter selection ├── @actions/ # Server actions ├── data/ # SQL migrations ├── infrastructure/ # Postgres bootstrap scripts ├── public/ # Static assets, firebase-messaging-sw.js ├── locales/ # i18n translation files ├── env.local.template # Single source of truth for env vars └── ring-config.json # Clone configuration ``` ## Testing {`npm run test # Unit tests npm run test:integration # Integration tests npm run test:e2e # End-to-end tests`} ## Common Issues ### Port 3000 Already in Use {`npm run dev -- -p 3001`} ### Database Connection Refused 1. Verify PostgreSQL is running: `pg_isready` 2. Check `.env.local` values for `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` 3. Ensure database `ring_platform` exists 4. Confirm `DB_BACKEND_MODE` is set to `k8s-postgres-fcm` ### Auth.js OAuth Errors 1. Verify `AUTH_GOOGLE_ID` and `AUTH_GOOGLE_SECRET` in `.env.local` 2. Check that `http://localhost:3000` is in the Google OAuth console authorized redirect URIs 3. Ensure `AUTH_SECRET` is set and consistent 4. Callback URL format: `http://localhost:3000/api/auth/callback/google` ### Firebase FCM Not Working (Optional) Firebase is used only for push notifications (FCM) in `k8s-postgres-fcm` mode. The app will work without Firebase configured, but push notifications will not be delivered. Configure `AUTH_FIREBASE_*` and `NEXT_PUBLIC_FIREBASE_*` vars if needed. ## Next Steps - [Environment Configuration](/docs/en/deployment/environment.md) — Full env var reference - [Deployment](/docs/en/development/deployment.md) — Deploying to production - [Installation Guide](/docs/en/getting-started/installation.md) — Production installation - [Code Structure](/docs/en/development/code-structure.md) — Codebase organization - [Development Workflow](/docs/en/development/workflow.md) — Git workflow and best practices - [Testing](/docs/en/development/testing.md) — Writing and running tests --- Need help? Check the [troubleshooting guide](/docs/en/getting-started/troubleshooting.md) or join our [Discord Community](https://discord.gg/ring-platform).