# 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:

| Service | Purpose | Sign-up URL |
|---------|---------|-------------|
| MongoDB Atlas | Database hosting | https://www.mongodb.com/cloud/atlas/register |
| AWS | S3 storage for media files | https://aws.amazon.com/ |
| Fly.io | Application hosting | https://fly.io/app/sign-up |
| Brevo | Transactional email | https://www.brevo.com/free-signup/ |
| Ramblers | Walks Manager API access | Contact Ramblers IT |

### Optional Services

| Service | Purpose | Sign-up URL |
|---------|---------|-------------|
| Google Cloud | Maps, Places, and Geocoding APIs | https://console.cloud.google.com/ |
| Ordnance Survey | UK mapping tiles | https://osdatahub.os.uk/ |
| Facebook | Social events integration | https://developers.facebook.com/ |
| Meetup | Event synchronisation | https://www.meetup.com/api/oauth/list/ |
| reCAPTCHA | Form spam protection | https://www.google.com/recaptcha/admin |

## 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:
   ```json
   {
     "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:
   ```bash
   mongodump --uri="mongodb+srv://user:pass@cluster.mongodb.net/source-db" --out=./backup
   ```

2. Import to the new database:
   ```bash
   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

```bash
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:

| File | Purpose |
|------|---------|
| `non-vcs/secrets/secrets.{appName}.env` | Environment variables |
| `non-vcs/fly-io/configs.json` | Fly.io deployment config |

## Deploying to Fly.io

After running the setup wizard:

1. **Create the Fly.io app:**
   ```bash
   fly apps create ngx-ramblers-mygroup --org personal
   ```

2. **Import secrets:**
   ```bash
   fly secrets import < non-vcs/secrets/secrets.ngx-ramblers-mygroup.env -a ngx-ramblers-mygroup
   ```

3. **Deploy:**
   ```bash
   fly deploy -a ngx-ramblers-mygroup
   ```

4. **Verify:**
   ```bash
   fly status -a ngx-ramblers-mygroup
   fly logs -a ngx-ramblers-mygroup
   ```

## Environment Variables Reference

| Variable | Required | Description |
|----------|----------|-------------|
| `NODE_ENV` | Yes | Set to `production` |
| `MONGODB_URI` | Yes | Full MongoDB connection string |
| `AUTH_SECRET` | Yes | 32-byte secret for JWT signing |
| `AWS_ACCESS_KEY_ID` | Yes | S3 access key |
| `AWS_SECRET_ACCESS_KEY` | Yes | S3 secret key |
| `AWS_BUCKET` | Yes | S3 bucket name |
| `AWS_REGION` | Yes | S3 region |
| `GOOGLE_MAPS_APIKEY` | No | Google Maps API key |
| `FACEBOOK_APP_ID` | No | Facebook application ID |
| `FACEBOOK_APP_SECRET` | No | Facebook application secret |
| `MEETUP_OAUTH_KEY` | No | Meetup OAuth consumer key |
| `MEETUP_OAUTH_SECRET` | No | Meetup OAuth consumer secret |
| `DEBUG` | No | Debug logging pattern |

## 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](https://fly.io/docs/)
- [MongoDB Atlas Documentation](https://www.mongodb.com/docs/atlas/)
- [AWS S3 Documentation](https://docs.aws.amazon.com/s3/)
- [Brevo API Documentation](https://developers.brevo.com/)