{"id":"697c9efc090375fa10a230ed","title":"2026 01 29 Environment Setup Prerequisites","path":"how-to/technical-articles/2026-01-29-environment-setup-prerequisites","contentMarkdown":"# 29-Jan-2026 — Environment Setup Prerequisites\n\n_____\n\nThis guide explains how to set up a new NGX-Ramblers environment for a Ramblers group, covering all required services, credentials, and configuration options.\n\n## Overview\n\nThe environment setup feature automates the provisioning of new NGX-Ramblers group instances. It orchestrates:\n\n- Ramblers API integration for group data\n- AWS S3 bucket and IAM user creation\n- MongoDB Atlas database initialisation\n- Fly.io deployment configuration\n- Email service (Brevo) configuration\n\nTwo interfaces are available:\n- **CLI Tool** — Interactive command-line wizard\n- **Web UI** — Admin panel wizard (staging environments only)\n\n## Prerequisites\n\nBefore starting, ensure you have accounts and access to:\n\n| Service | Purpose | Sign-up URL |\n|---------|---------|-------------|\n| MongoDB Atlas | Database hosting | https://www.mongodb.com/cloud/atlas/register |\n| AWS | S3 storage for media files | https://aws.amazon.com/ |\n| Fly.io | Application hosting | https://fly.io/app/sign-up |\n| Brevo | Transactional email | https://www.brevo.com/free-signup/ |\n| Ramblers | Walks Manager API access | Contact Ramblers IT |\n\n### Optional Services\n\n| Service | Purpose | Sign-up URL |\n|---------|---------|-------------|\n| Google Cloud | Maps, Places, and Geocoding APIs | https://console.cloud.google.com/ |\n| Ordnance Survey | UK mapping tiles | https://osdatahub.os.uk/ |\n| Facebook | Social events integration | https://developers.facebook.com/ |\n| Meetup | Event synchronisation | https://www.meetup.com/api/oauth/list/ |\n| reCAPTCHA | Form spam protection | https://www.google.com/recaptcha/admin |\n\n## Required Credentials\n\n### Ramblers API\n\nContact Ramblers IT to obtain:\n- **API Key** — For Walks Manager API access\n- **Walks Manager Username/Password** (optional) — For walk synchronisation\n\n### MongoDB Atlas\n\n1. Create a cluster (M0 free tier is sufficient for small groups)\n2. Create a database user with read/write access\n3. Whitelist your IP addresses (or allow access from anywhere for Fly.io)\n4. Note your cluster hostname (e.g., `cluster0.abc123`)\n\n**Required values:**\n- Cluster hostname (without `.mongodb.net`)\n- Database username\n- Database password\n- Database name (e.g., `ngx-ramblers-mygroup`)\n\n### AWS S3\n\nFor automated bucket creation, you need AWS admin credentials. Alternatively, create the bucket manually.\n\n**For automated setup**, provide:\n- `AWS_ACCESS_KEY_ID` — Admin access key\n- `AWS_SECRET_ACCESS_KEY` — Admin secret key\n- `AWS_REGION` — Region (default: `eu-west-1`)\n\n**For manual setup**, create:\n1. An S3 bucket named `ngx-ramblers-{groupname}`\n2. An IAM user with S3 access to that bucket\n3. Access credentials for the IAM user\n\n### Brevo Email\n\n1. Sign up at https://www.brevo.com/\n2. Navigate to SMTP & API → API Keys\n3. Generate an API key\n\n### Fly.io\n\n1. Install the Fly CLI: `curl -L https://fly.io/install.sh | sh`\n2. Authenticate: `fly auth login`\n3. Note your organisation name (usually \"personal\")\n\n### Facebook (Optional)\n\nFor Facebook social events integration:\n\n1. Go to https://developers.facebook.com/\n2. Create a new app (Consumer type)\n3. Add the Facebook Login product\n4. Configure OAuth settings with your domain\n5. Note your App ID and App Secret\n\n**Required values:**\n- `FACEBOOK_APP_ID` — Application ID\n- `FACEBOOK_APP_SECRET` — Application secret\n\n### Meetup (Optional)\n\nFor Meetup event synchronisation:\n\n1. Go to https://www.meetup.com/api/oauth/list/\n2. Create a new OAuth Consumer\n3. Set the redirect URI to `https://yourdomain.com/api/meetup/oauth/callback`\n4. Note your OAuth credentials\n\n**Required values:**\n- `MEETUP_OAUTH_KEY` — OAuth consumer key\n- `MEETUP_OAUTH_SECRET` — OAuth consumer secret\n\n### Google Cloud (Optional)\n\nNGX-Ramblers uses multiple Google Cloud APIs. You need a single API key with access to:\n\n**Required APIs to enable:**\n- **Maps JavaScript API** — Interactive maps on walk pages\n- **Places API (New)** — Venue search and autocomplete\n- **Geocoding API** — Converting postcodes to coordinates\n\n**Setup steps:**\n\n1. Go to https://console.cloud.google.com/\n2. Create a new project (or select existing)\n3. Navigate to APIs & Services → Library\n4. Enable each of the three APIs listed above\n5. Navigate to APIs & Services → Credentials\n6. Create an API key\n7. Restrict the key to your domain(s) for security\n8. Restrict the key to only the required APIs\n\n**Required value:**\n- `GOOGLE_MAPS_APIKEY` — Single API key for all Google services\n\n**Billing note:** Google Cloud requires a billing account, but provides a generous free tier ($200/month credit) that covers most small group usage.\n\n## AWS IAM Setup for Multi-Environment Management\n\nIf you're managing multiple group environments, set up a master AWS account with delegated access.\n\n### Master Account Setup\n\n1. Create an IAM user for environment provisioning:\n ```\n User name: ngx-ramblers-provisioner\n Access type: Programmatic access\n ```\n\n2. Attach a custom policy allowing S3 and IAM operations:\n ```json\n {\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"s3:CreateBucket\",\n \"s3:PutBucketCors\",\n \"s3:PutBucketPolicy\",\n \"s3:PutPublicAccessBlock\"\n ],\n \"Resource\": \"arn:aws:s3:::ngx-ramblers-*\"\n },\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"iam:CreateUser\",\n \"iam:CreateAccessKey\",\n \"iam:PutUserPolicy\",\n \"iam:AttachUserPolicy\"\n ],\n \"Resource\": \"arn:aws:iam::*:user/ngx-ramblers-*\"\n }\n ]\n }\n ```\n\n3. Store the access credentials securely (e.g., in a password manager)\n\n### Per-Environment Credentials\n\nThe setup process creates:\n- A dedicated IAM user per environment (e.g., `ngx-ramblers-mygroup-user`)\n- A bucket-specific policy with least-privilege access\n- Access credentials stored in the secrets file\n\nThis ensures each environment has isolated credentials that can be rotated independently.\n\n## Database Initialisation Options\n\n### Option 1: Fresh Database (Recommended for New Groups)\n\nThe setup wizard creates:\n- Configuration documents (system, Brevo, committee, walks)\n- Initial admin user account\n- System member account\n- Optional sample page content\n\n### Option 2: Restore from Backup\n\nFor migrating an existing group:\n\n1. Export the source database:\n ```bash\n mongodump --uri=\"mongodb+srv://user:pass@cluster.mongodb.net/source-db\" --out=./backup\n ```\n\n2. Import to the new database:\n ```bash\n mongorestore --uri=\"mongodb+srv://user:pass@cluster.mongodb.net/new-db\" ./backup/source-db\n ```\n\n3. Update configuration documents with new credentials (AWS, Brevo, etc.)\n\n### Option 3: Clone Existing Environment\n\nUse MongoDB Atlas's built-in backup/restore:\n1. Create a snapshot of the source cluster\n2. Restore to the target cluster with a new database name\n3. Update credentials in the `config` collection\n\n## Using the CLI Tool\n\n### Running the Wizard\n\n```bash\ncd server\nnpx tsx deploy/create-environment-cli.ts\n```\n\n### Interactive Steps\n\n1. **AWS Credentials** (optional)\n - Enter admin credentials for automated S3 setup\n - Skip to create bucket manually\n\n2. **Ramblers API Key**\n - Enter your API key\n - Validated against the Ramblers API\n\n3. **Group Selection**\n - Enter group code directly (e.g., `01SURREY`)\n - Or browse by area code (e.g., `01` for Surrey)\n\n4. **Environment Configuration**\n - Environment name (derived from group name)\n - Fly.io app name\n - Memory allocation (MB)\n - Instance count\n\n5. **MongoDB Configuration**\n - Cluster hostname\n - Username and password\n - Database name\n\n6. **AWS S3 Configuration**\n - Bucket name\n - Region\n\n7. **Email Configuration**\n - Brevo API key\n\n8. **Optional Services**\n - Google Maps API key\n - Walks Manager credentials\n\n9. **Admin User**\n - Name, email, and password\n\n10. **Setup Options**\n - Include sample pages\n - Include notification configs\n - Skip Fly.io deployment\n\n### Output Files\n\nThe wizard creates:\n\n| File | Purpose |\n|------|---------|\n| `non-vcs/secrets/secrets.{appName}.env` | Environment variables |\n| `non-vcs/fly-io/configs.json` | Fly.io deployment config |\n\n## Deploying to Fly.io\n\nAfter running the setup wizard:\n\n1. **Create the Fly.io app:**\n ```bash\n fly apps create ngx-ramblers-mygroup --org personal\n ```\n\n2. **Import secrets:**\n ```bash\n fly secrets import < non-vcs/secrets/secrets.ngx-ramblers-mygroup.env -a ngx-ramblers-mygroup\n ```\n\n3. **Deploy:**\n ```bash\n fly deploy -a ngx-ramblers-mygroup\n ```\n\n4. **Verify:**\n ```bash\n fly status -a ngx-ramblers-mygroup\n fly logs -a ngx-ramblers-mygroup\n ```\n\n## Environment Variables Reference\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `NODE_ENV` | Yes | Set to `production` |\n| `MONGODB_URI` | Yes | Full MongoDB connection string |\n| `AUTH_SECRET` | Yes | 32-byte secret for JWT signing |\n| `AWS_ACCESS_KEY_ID` | Yes | S3 access key |\n| `AWS_SECRET_ACCESS_KEY` | Yes | S3 secret key |\n| `AWS_BUCKET` | Yes | S3 bucket name |\n| `AWS_REGION` | Yes | S3 region |\n| `GOOGLE_MAPS_APIKEY` | No | Google Maps API key |\n| `FACEBOOK_APP_ID` | No | Facebook application ID |\n| `FACEBOOK_APP_SECRET` | No | Facebook application secret |\n| `MEETUP_OAUTH_KEY` | No | Meetup OAuth consumer key |\n| `MEETUP_OAUTH_SECRET` | No | Meetup OAuth consumer secret |\n| `DEBUG` | No | Debug logging pattern |\n\n## Troubleshooting\n\n### MongoDB Connection Errors\n\n- Verify the cluster hostname is correct (without `.mongodb.net`)\n- Check the username and password are URL-encoded if they contain special characters\n- Ensure the IP whitelist includes Fly.io's IP ranges (or use 0.0.0.0/0)\n\n### AWS S3 Errors\n\n- Verify the IAM user has the required permissions\n- Check the bucket name is globally unique\n- Ensure CORS is configured for browser uploads\n\n### Fly.io Deployment Issues\n\n- Check logs: `fly logs -a appname`\n- Verify secrets are set: `fly secrets list -a appname`\n- Check machine status: `fly status -a appname`\n\n## Related Documentation\n\n- [Fly.io Documentation](https://fly.io/docs/)\n- [MongoDB Atlas Documentation](https://www.mongodb.com/docs/atlas/)\n- [AWS S3 Documentation](https://docs.aws.amazon.com/s3/)\n- [Brevo API Documentation](https://developers.brevo.com/)\n","contentHtml":"

29-Jan-2026 — Environment Setup Prerequisites

\n
\n

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

\n

Overview

\n

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

\n\n

Two interfaces are available:

\n\n

Prerequisites

\n

Before starting, ensure you have accounts and access to:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ServicePurposeSign-up URL
MongoDB AtlasDatabase hostinghttps://www.mongodb.com/cloud/atlas/register
AWSS3 storage for media fileshttps://aws.amazon.com/
Fly.ioApplication hostinghttps://fly.io/app/sign-up
BrevoTransactional emailhttps://www.brevo.com/free-signup/
RamblersWalks Manager API accessContact Ramblers IT
\n

Optional Services

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ServicePurposeSign-up URL
Google CloudMaps, Places, and Geocoding APIshttps://console.cloud.google.com/
Ordnance SurveyUK mapping tileshttps://osdatahub.os.uk/
FacebookSocial events integrationhttps://developers.facebook.com/
MeetupEvent synchronisationhttps://www.meetup.com/api/oauth/list/
reCAPTCHAForm spam protectionhttps://www.google.com/recaptcha/admin
\n

Required Credentials

\n

Ramblers API

\n

Contact Ramblers IT to obtain:

\n\n

MongoDB Atlas

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

Required values:

\n\n

AWS S3

\n

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

\n

For automated setup, provide:

\n\n

For manual setup, create:

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

Brevo Email

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

Fly.io

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

Facebook (Optional)

\n

For Facebook social events integration:

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

Required values:

\n\n

Meetup (Optional)

\n

For Meetup event synchronisation:

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

Required values:

\n\n

Google Cloud (Optional)

\n

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

\n

Required APIs to enable:

\n\n

Setup steps:

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

Required value:

\n\n

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

\n

AWS IAM Setup for Multi-Environment Management

\n

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

\n

Master Account Setup

\n
    \n

  1. Create an IAM user for environment provisioning:

    \n
    User name: ngx-ramblers-provisioner\nAccess type: Programmatic access\n
    \n
    2. \n

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

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

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

    \n
    4. \n
\n

Per-Environment Credentials

\n

The setup process creates:

\n\n

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

\n

Database Initialisation Options

\n

Option 1: Fresh Database (Recommended for New Groups)

\n

The setup wizard creates:

\n\n

Option 2: Restore from Backup

\n

For migrating an existing group:

\n
    \n

  1. Export the source database:

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

  2. Import to the new database:

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

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

    \n
    4. \n
\n

Option 3: Clone Existing Environment

\n

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

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

Using the CLI Tool

\n

Running the Wizard

\n
cd server\nnpx tsx deploy/create-environment-cli.ts\n
\n

Interactive Steps

\n
    \n

  1. AWS Credentials (optional)

    \n\n
    2. \n

  2. Ramblers API Key

    \n\n
    3. \n

  3. Group Selection

    \n\n
    4. \n

  4. Environment Configuration

    \n\n
    5. \n

  5. MongoDB Configuration

    \n\n
    6. \n

  6. AWS S3 Configuration

    \n\n
    7. \n

  7. Email Configuration

    \n\n
    8. \n

  8. Optional Services

    \n\n
    9. \n

  9. Admin User

    \n\n
    10. \n

  10. Setup Options

    \n\n
    11. \n
\n

Output Files

\n

The wizard creates:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FilePurpose
non-vcs/secrets/secrets.{appName}.envEnvironment variables
non-vcs/fly-io/configs.jsonFly.io deployment config
\n

Deploying to Fly.io

\n

After running the setup wizard:

\n
    \n

  1. Create the Fly.io app:

    \n
    fly apps create ngx-ramblers-mygroup --org personal\n
    \n
    2. \n

  2. Import secrets:

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

  3. Deploy:

    \n
    fly deploy -a ngx-ramblers-mygroup\n
    \n
    4. \n

  4. Verify:

    \n
    fly status -a ngx-ramblers-mygroup\nfly logs -a ngx-ramblers-mygroup\n
    \n
    5. \n
\n

Environment Variables Reference

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
VariableRequiredDescription
NODE_ENVYesSet to production
MONGODB_URIYesFull MongoDB connection string
AUTH_SECRETYes32-byte secret for JWT signing
AWS_ACCESS_KEY_IDYesS3 access key
AWS_SECRET_ACCESS_KEYYesS3 secret key
AWS_BUCKETYesS3 bucket name
AWS_REGIONYesS3 region
GOOGLE_MAPS_APIKEYNoGoogle Maps API key
FACEBOOK_APP_IDNoFacebook application ID
FACEBOOK_APP_SECRETNoFacebook application secret
MEETUP_OAUTH_KEYNoMeetup OAuth consumer key
MEETUP_OAUTH_SECRETNoMeetup OAuth consumer secret
DEBUGNoDebug logging pattern
\n

Troubleshooting

\n

MongoDB Connection Errors

\n\n

AWS S3 Errors

\n\n

Fly.io Deployment Issues

\n\n

Related Documentation

\n\n"}