29-Jan-2026 — Environment Setup Prerequisites

This guide explains how to set up a new NGX-Ramblers environment for a Ramblers group, covering all required services, credentials, and configuration options.

Overview

The environment setup feature automates the provisioning of new NGX-Ramblers group instances. It orchestrates:

• Ramblers API integration for group data
• AWS S3 bucket and IAM user creation
• MongoDB Atlas database initialisation
• Fly.io deployment configuration
• Email service (Brevo) configuration

Two interfaces are available:

• CLI Tool — Interactive command-line wizard
• Web UI — Admin panel wizard (staging environments only)

Prerequisites

Before starting, ensure you have accounts and access to:

Optional Services

Required Credentials

Ramblers API

Contact Ramblers IT to obtain:

• API Key — For Walks Manager API access
• Walks Manager Username/Password (optional) — For walk synchronisation

MongoDB Atlas

1. Create a cluster (M0 free tier is sufficient for small groups)
2. Create a database user with read/write access
3. Whitelist your IP addresses (or allow access from anywhere for Fly.io)
4. Note your cluster hostname (e.g., cluster0.abc123)

Required values:

• Cluster hostname (without .mongodb.net)
• Database username
• Database password
• Database name (e.g., ngx-ramblers-mygroup)

AWS S3

For automated bucket creation, you need AWS admin credentials. Alternatively, create the bucket manually.

For automated setup, provide:

• AWS_ACCESS_KEY_ID — Admin access key
• AWS_SECRET_ACCESS_KEY — Admin secret key
• AWS_REGION — Region (default: eu-west-1)

For manual setup, create:

1. An S3 bucket named ngx-ramblers-{groupname}
2. An IAM user with S3 access to that bucket
3. Access credentials for the IAM user

Brevo Email

1. Sign up at https://www.brevo.com/
2. Navigate to SMTP & API → API Keys
3. Generate an API key

Fly.io

1. Install the Fly CLI: curl -L https://fly.io/install.sh | sh
2. Authenticate: fly auth login
3. Note your organisation name (usually "personal")

Facebook (Optional)

For Facebook social events integration:

1. Go to https://developers.facebook.com/
2. Create a new app (Consumer type)
3. Add the Facebook Login product
4. Configure OAuth settings with your domain
5. Note your App ID and App Secret

Required values:

• FACEBOOK_APP_ID — Application ID
• FACEBOOK_APP_SECRET — Application secret

Meetup (Optional)

For Meetup event synchronisation:

1. Go to https://www.meetup.com/api/oauth/list/
2. Create a new OAuth Consumer
3. Set the redirect URI to https://yourdomain.com/api/meetup/oauth/callback
4. Note your OAuth credentials

Required values:

• MEETUP_OAUTH_KEY — OAuth consumer key
• MEETUP_OAUTH_SECRET — OAuth consumer secret

Google Cloud (Optional)

NGX-Ramblers uses multiple Google Cloud APIs. You need a single API key with access to:

Required APIs to enable:

• Maps JavaScript API — Interactive maps on walk pages
• Places API (New) — Venue search and autocomplete
• Geocoding API — Converting postcodes to coordinates

Setup steps:

1. Go to https://console.cloud.google.com/
2. Create a new project (or select existing)
3. Navigate to APIs & Services → Library
4. Enable each of the three APIs listed above
5. Navigate to APIs & Services → Credentials
6. Create an API key
7. Restrict the key to your domain(s) for security
8. Restrict the key to only the required APIs

Required value:

• GOOGLE_MAPS_APIKEY — Single API key for all Google services

Billing note: Google Cloud requires a billing account, but provides a generous free tier ($200/month credit) that covers most small group usage.

AWS IAM Setup for Multi-Environment Management

If you're managing multiple group environments, set up a master AWS account with delegated access.

Master Account Setup

1. Create an IAM user for environment provisioning:

   User name: ngx-ramblers-provisioner
   Access type: Programmatic access
   

2. Attach a custom policy allowing S3 and IAM operations:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:CreateBucket",
           "s3:PutBucketCors",
           "s3:PutBucketPolicy",
           "s3:PutPublicAccessBlock"
         ],
         "Resource": "arn:aws:s3:::ngx-ramblers-*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "iam:CreateUser",
           "iam:CreateAccessKey",
           "iam:PutUserPolicy",
           "iam:AttachUserPolicy"
         ],
         "Resource": "arn:aws:iam::*:user/ngx-ramblers-*"
       }
     ]
   }
   

3. Store the access credentials securely (e.g., in a password manager)

Per-Environment Credentials

The setup process creates:

• A dedicated IAM user per environment (e.g., ngx-ramblers-mygroup-user)
• A bucket-specific policy with least-privilege access
• Access credentials stored in the secrets file

This ensures each environment has isolated credentials that can be rotated independently.

Database Initialisation Options

Option 1: Fresh Database (Recommended for New Groups)

The setup wizard creates:

• Configuration documents (system, Brevo, committee, walks)
• Initial admin user account
• System member account
• Optional sample page content

Option 2: Restore from Backup

For migrating an existing group:

1. Export the source database:

   mongodump --uri="mongodb+srv://user:pass@cluster.mongodb.net/source-db" --out=./backup
   

2. Import to the new database:

   mongorestore --uri="mongodb+srv://user:pass@cluster.mongodb.net/new-db" ./backup/source-db
   

3. Update configuration documents with new credentials (AWS, Brevo, etc.)

Option 3: Clone Existing Environment

Use MongoDB Atlas's built-in backup/restore:

1. Create a snapshot of the source cluster
2. Restore to the target cluster with a new database name
3. Update credentials in the config collection

Using the CLI Tool

Running the Wizard

cd server
npx tsx deploy/create-environment-cli.ts

Interactive Steps

1. AWS Credentials (optional)

   • Enter admin credentials for automated S3 setup
   • Skip to create bucket manually

2. Ramblers API Key

   • Enter your API key
   • Validated against the Ramblers API

3. Group Selection

   • Enter group code directly (e.g., 01SURREY)
   • Or browse by area code (e.g., 01 for Surrey)

4. Environment Configuration

   • Environment name (derived from group name)
   • Fly.io app name
   • Memory allocation (MB)
   • Instance count

5. MongoDB Configuration

   • Cluster hostname
   • Username and password
   • Database name

6. AWS S3 Configuration

   • Bucket name
   • Region

7. Email Configuration

   • Brevo API key

8. Optional Services

   • Google Maps API key
   • Walks Manager credentials

9. Admin User

   • Name, email, and password

10. Setup Options

    • Include sample pages
    • Include notification configs
    • Skip Fly.io deployment

Output Files

The wizard creates:

Deploying to Fly.io

After running the setup wizard:

1. Create the Fly.io app:

   fly apps create ngx-ramblers-mygroup --org personal
   

2. Import secrets:

   fly secrets import < non-vcs/secrets/secrets.ngx-ramblers-mygroup.env -a ngx-ramblers-mygroup
   

3. Deploy:

   fly deploy -a ngx-ramblers-mygroup
   

4. Verify:

   fly status -a ngx-ramblers-mygroup
   fly logs -a ngx-ramblers-mygroup
   

Environment Variables Reference

Troubleshooting

MongoDB Connection Errors

• Verify the cluster hostname is correct (without .mongodb.net)
• Check the username and password are URL-encoded if they contain special characters
• Ensure the IP whitelist includes Fly.io's IP ranges (or use 0.0.0.0/0)

AWS S3 Errors

• Verify the IAM user has the required permissions
• Check the bucket name is globally unique
• Ensure CORS is configured for browser uploads

Fly.io Deployment Issues

• Check logs: fly logs -a appname
• Verify secrets are set: fly secrets list -a appname
• Check machine status: fly status -a appname

Related Documentation

• Fly.io Documentation
• MongoDB Atlas Documentation
• AWS S3 Documentation
• Brevo API Documentation