# 30-Jan-2026 — Environment Setup Guide

The Environment Setup page allows administrators to create complete NGX-Ramblers environments for new Ramblers walking groups. This guide walks through the wizard interface and explains each step.

## Accessing Environment Setup

Navigate to **Admin > Environment Setup** from the main menu.

You'll see two options:
- **Create New Environment** - Set up a brand new environment for a Ramblers group
- **Manage Existing Environment** - Resume setup, update, or destroy an existing environment

---

## Creating a New Environment

### Step 1: Group Selection

This step validates your Ramblers API credentials and lets you select your walking group.

1. **Enter your Ramblers API Key**
   - Obtain this from the Ramblers volunteer portal
   - Click "Validate API Key" to verify it works

2. **Search for your group**
   - Once validated, enter your group name or code in the search box
   - Select your group from the search results
   - The system will display group details including:
     - Group name and code
     - Area name and code
     - Contact information

3. **Review group information**
   - Verify the displayed information is correct
   - Click "Next" to proceed

### Step 2: Service Configuration

Configure the external services required for your environment.

#### MongoDB Database

Your environment needs a MongoDB database. You can:
- Use MongoDB Atlas (recommended) - free tier available
- Use an existing MongoDB instance

Enter your connection details:
- **Cluster**: The cluster hostname (e.g., `cluster0.abc123.mongodb.net`)
- **Username**: Database username
- **Password**: Database password
- **Database**: Database name (e.g., `ngx-ramblers-yourgroup`)

Click "Test Connection" to verify the database is accessible.

#### AWS S3 Storage

File storage for images, documents, and backups.

If you have AWS credentials with admin access:
- Leave fields blank - the wizard will create resources automatically
- S3 bucket and IAM user will be provisioned for you

If you have existing AWS credentials:
- Enter the Access Key ID
- Enter the Secret Access Key
- Enter the Bucket name
- Enter the Region

#### Brevo Email Service

For sending transactional emails (password resets, notifications).

- Enter your Brevo API Key
- Obtain this from your Brevo account settings

#### Google Maps (Optional)

For displaying walk routes and meeting point maps.

- Enter your Google Maps API Key
- Required for map features to work

#### OS Maps (Optional)

For displaying Ordnance Survey maps.

- Enter your OS Maps API Key
- Provides UK-specific mapping

#### reCAPTCHA (Optional)

For spam protection on public forms.

- Enter Site Key
- Enter Secret Key

### Step 3: Admin User Setup

Create the first administrator account for your new environment.

Enter:
- **First Name**
- **Last Name**
- **Email Address** - This will be the login username
- **Initial Password** - Must meet security requirements

This user will have full admin access to manage the site.

### Step 4: Deployment Options

Configure how your environment will be deployed.

#### fly.io Deployment Settings

- **App Name**: Auto-generated from your group name (can be customised)
- **Memory**: Recommended 1GB for production use
- **Scale Count**: Number of instances (1 is sufficient for most groups)
- **Organisation**: Your fly.io organisation (usually "personal")

#### Options

- **Include sample notification configs**: Creates default email notification templates
- **Deploy to fly.io now**: Starts deployment immediately after creation

### Step 5: Review and Create

Review all your configuration before creating the environment.

The summary shows:
- Group information
- Service configurations (with sensitive values masked)
- Admin user details
- Deployment settings

Click **Create Environment** to start the provisioning process.

---

## Environment Creation Progress

Once you click "Create Environment", the wizard shows real-time progress:

1. **Creating AWS Resources**
   - S3 bucket creation
   - IAM user and policy setup
   - Access key generation

2. **Initialising Database**
   - Creating collections
   - Setting up system configuration
   - Creating admin user account
   - Running database migrations
   - Populating admin menu items

3. **Deploying to fly.io** (if selected)
   - Creating fly.io application
   - Setting environment secrets
   - Deploying application code
   - Health check verification

Each step shows:
- ⏳ Running (in progress)
- ✅ Completed (successful)
- ❌ Failed (with error message)

If any step fails, you can use "Manage Existing Environment" to resume.

---

## Managing Existing Environments

### Resume Setup

If environment creation was interrupted:

1. Select "Manage Existing Environment"
2. Choose your environment from the list
3. Select "Resume Setup"
4. Choose which steps to run:
   - **Database Initialisation**: Re-run database setup
   - **fly.io Deployment**: Deploy or redeploy to fly.io

### Update Environment

Update an existing environment's configuration:

- Update Ramblers API information
- Change deployment settings
- Modify service credentials

### Destroy Environment

Permanently remove an environment and all its resources:

1. Select "Manage Existing Environment"
2. Choose your environment
3. Select "Destroy"
4. Confirm the destruction

This will remove:
- fly.io application
- S3 bucket and all files
- IAM user and credentials
- Database collections (cleared, not dropped)
- Local configuration files

**Warning**: This action cannot be undone.

---

## Post-Setup Tasks

After your environment is created:

### 1. Access Your New Site

Navigate to `https://your-app-name.fly.dev` to see your new site.

### 2. Log In as Admin

Use the admin credentials you created during setup.

### 3. Configure Site Settings

Go to **Admin > System Settings** to:
- Upload your group logo
- Configure email templates
- Set up committee members
- Customise site appearance

### 4. Import Walks Data

The system can automatically sync walks from the Ramblers API:
- Go to **Walks** page
- Click **Admin** (if you have committee access)
- Use the sync function to pull walks data

### 5. Customise Page Content

Edit the default page content:
- Home page welcome message
- About Us information
- Contact details
- Walks information page

---

## Troubleshooting

### "API Key validation failed"

- Verify your Ramblers API key is correct
- Check the key hasn't expired
- Ensure you have the correct permissions

### "Database connection failed"

- Verify connection string components are correct
- Check the database user has appropriate permissions
- Ensure your IP address is whitelisted (for MongoDB Atlas)

### "AWS resource creation failed"

- Verify AWS credentials have admin permissions
- Check IAM policies allow S3 and IAM operations
- Ensure bucket name doesn't already exist (globally unique)

### "fly.io deployment failed"

- Verify FLY_API_TOKEN is set correctly
- Check you have sufficient fly.io resources
- Review fly.io dashboard for detailed error logs

### Resuming Failed Setup

If creation fails partway through:

1. Note which step failed
2. Fix the underlying issue (credentials, permissions, etc.)
3. Use "Manage Existing Environment" > "Resume Setup"
4. Select the appropriate options to complete setup

---

## CLI Alternative

For power users, all these operations are also available via command line.

See the **NGX Ramblers CLI Reference Guide** in Technical Documents for:
- `ngx-cli env resume` - Resume environment setup
- `ngx-cli f deploy` - Deploy to fly.io
- `ngx-cli db seed --fresh --sync` - Fresh database setup with data sync
- `ngx-cli des` - Destroy environment

The CLI provides the same functionality with additional automation options.