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.