{"id":"697c9f09090375fa10a230f9","title":"2026 01 30 Environment Setup Guide","path":"how-to/technical-articles/2026-01-30-environment-setup-guide","contentMarkdown":"# 30-Jan-2026 — Environment Setup Guide\n\nThe 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.\n\n## Accessing Environment Setup\n\nNavigate to **Admin > Environment Setup** from the main menu.\n\nYou'll see two options:\n- **Create New Environment** - Set up a brand new environment for a Ramblers group\n- **Manage Existing Environment** - Resume setup, update, or destroy an existing environment\n\n---\n\n## Creating a New Environment\n\n### Step 1: Group Selection\n\nThis step validates your Ramblers API credentials and lets you select your walking group.\n\n1. **Enter your Ramblers API Key**\n - Obtain this from the Ramblers volunteer portal\n - Click \"Validate API Key\" to verify it works\n\n2. **Search for your group**\n - Once validated, enter your group name or code in the search box\n - Select your group from the search results\n - The system will display group details including:\n - Group name and code\n - Area name and code\n - Contact information\n\n3. **Review group information**\n - Verify the displayed information is correct\n - Click \"Next\" to proceed\n\n### Step 2: Service Configuration\n\nConfigure the external services required for your environment.\n\n#### MongoDB Database\n\nYour environment needs a MongoDB database. You can:\n- Use MongoDB Atlas (recommended) - free tier available\n- Use an existing MongoDB instance\n\nEnter your connection details:\n- **Cluster**: The cluster hostname (e.g., `cluster0.abc123.mongodb.net`)\n- **Username**: Database username\n- **Password**: Database password\n- **Database**: Database name (e.g., `ngx-ramblers-yourgroup`)\n\nClick \"Test Connection\" to verify the database is accessible.\n\n#### AWS S3 Storage\n\nFile storage for images, documents, and backups.\n\nIf you have AWS credentials with admin access:\n- Leave fields blank - the wizard will create resources automatically\n- S3 bucket and IAM user will be provisioned for you\n\nIf you have existing AWS credentials:\n- Enter the Access Key ID\n- Enter the Secret Access Key\n- Enter the Bucket name\n- Enter the Region\n\n#### Brevo Email Service\n\nFor sending transactional emails (password resets, notifications).\n\n- Enter your Brevo API Key\n- Obtain this from your Brevo account settings\n\n#### Google Maps (Optional)\n\nFor displaying walk routes and meeting point maps.\n\n- Enter your Google Maps API Key\n- Required for map features to work\n\n#### OS Maps (Optional)\n\nFor displaying Ordnance Survey maps.\n\n- Enter your OS Maps API Key\n- Provides UK-specific mapping\n\n#### reCAPTCHA (Optional)\n\nFor spam protection on public forms.\n\n- Enter Site Key\n- Enter Secret Key\n\n### Step 3: Admin User Setup\n\nCreate the first administrator account for your new environment.\n\nEnter:\n- **First Name**\n- **Last Name**\n- **Email Address** - This will be the login username\n- **Initial Password** - Must meet security requirements\n\nThis user will have full admin access to manage the site.\n\n### Step 4: Deployment Options\n\nConfigure how your environment will be deployed.\n\n#### fly.io Deployment Settings\n\n- **App Name**: Auto-generated from your group name (can be customised)\n- **Memory**: Recommended 1GB for production use\n- **Scale Count**: Number of instances (1 is sufficient for most groups)\n- **Organisation**: Your fly.io organisation (usually \"personal\")\n\n#### Options\n\n- **Include sample notification configs**: Creates default email notification templates\n- **Deploy to fly.io now**: Starts deployment immediately after creation\n\n### Step 5: Review and Create\n\nReview all your configuration before creating the environment.\n\nThe summary shows:\n- Group information\n- Service configurations (with sensitive values masked)\n- Admin user details\n- Deployment settings\n\nClick **Create Environment** to start the provisioning process.\n\n---\n\n## Environment Creation Progress\n\nOnce you click \"Create Environment\", the wizard shows real-time progress:\n\n1. **Creating AWS Resources**\n - S3 bucket creation\n - IAM user and policy setup\n - Access key generation\n\n2. **Initialising Database**\n - Creating collections\n - Setting up system configuration\n - Creating admin user account\n - Running database migrations\n - Populating admin menu items\n\n3. **Deploying to fly.io** (if selected)\n - Creating fly.io application\n - Setting environment secrets\n - Deploying application code\n - Health check verification\n\nEach step shows:\n- ⏳ Running (in progress)\n- ✅ Completed (successful)\n- ❌ Failed (with error message)\n\nIf any step fails, you can use \"Manage Existing Environment\" to resume.\n\n---\n\n## Managing Existing Environments\n\n### Resume Setup\n\nIf environment creation was interrupted:\n\n1. Select \"Manage Existing Environment\"\n2. Choose your environment from the list\n3. Select \"Resume Setup\"\n4. Choose which steps to run:\n - **Database Initialisation**: Re-run database setup\n - **fly.io Deployment**: Deploy or redeploy to fly.io\n\n### Update Environment\n\nUpdate an existing environment's configuration:\n\n- Update Ramblers API information\n- Change deployment settings\n- Modify service credentials\n\n### Destroy Environment\n\nPermanently remove an environment and all its resources:\n\n1. Select \"Manage Existing Environment\"\n2. Choose your environment\n3. Select \"Destroy\"\n4. Confirm the destruction\n\nThis will remove:\n- fly.io application\n- S3 bucket and all files\n- IAM user and credentials\n- Database collections (cleared, not dropped)\n- Local configuration files\n\n**Warning**: This action cannot be undone.\n\n---\n\n## Post-Setup Tasks\n\nAfter your environment is created:\n\n### 1. Access Your New Site\n\nNavigate to `https://your-app-name.fly.dev` to see your new site.\n\n### 2. Log In as Admin\n\nUse the admin credentials you created during setup.\n\n### 3. Configure Site Settings\n\nGo to **Admin > System Settings** to:\n- Upload your group logo\n- Configure email templates\n- Set up committee members\n- Customise site appearance\n\n### 4. Import Walks Data\n\nThe system can automatically sync walks from the Ramblers API:\n- Go to **Walks** page\n- Click **Admin** (if you have committee access)\n- Use the sync function to pull walks data\n\n### 5. Customise Page Content\n\nEdit the default page content:\n- Home page welcome message\n- About Us information\n- Contact details\n- Walks information page\n\n---\n\n## Troubleshooting\n\n### \"API Key validation failed\"\n\n- Verify your Ramblers API key is correct\n- Check the key hasn't expired\n- Ensure you have the correct permissions\n\n### \"Database connection failed\"\n\n- Verify connection string components are correct\n- Check the database user has appropriate permissions\n- Ensure your IP address is whitelisted (for MongoDB Atlas)\n\n### \"AWS resource creation failed\"\n\n- Verify AWS credentials have admin permissions\n- Check IAM policies allow S3 and IAM operations\n- Ensure bucket name doesn't already exist (globally unique)\n\n### \"fly.io deployment failed\"\n\n- Verify FLY_API_TOKEN is set correctly\n- Check you have sufficient fly.io resources\n- Review fly.io dashboard for detailed error logs\n\n### Resuming Failed Setup\n\nIf creation fails partway through:\n\n1. Note which step failed\n2. Fix the underlying issue (credentials, permissions, etc.)\n3. Use \"Manage Existing Environment\" > \"Resume Setup\"\n4. Select the appropriate options to complete setup\n\n---\n\n## CLI Alternative\n\nFor power users, all these operations are also available via command line.\n\nSee the **NGX Ramblers CLI Reference Guide** in Technical Documents for:\n- `ngx-cli env resume` - Resume environment setup\n- `ngx-cli f deploy` - Deploy to fly.io\n- `ngx-cli db seed --fresh --sync` - Fresh database setup with data sync\n- `ngx-cli des` - Destroy environment\n\nThe CLI provides the same functionality with additional automation options.\n","contentHtml":"

30-Jan-2026 — Environment Setup Guide

\n

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.

\n

Accessing Environment Setup

\n

Navigate to Admin > Environment Setup from the main menu.

\n

You'll see two options:

\n\n
\n

Creating a New Environment

\n

Step 1: Group Selection

\n

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

\n
    \n

  1. Enter your Ramblers API Key

    \n\n
    2. \n

  2. Search for your group

    \n\n
    3. \n

  3. Review group information

    \n\n
    4. \n
\n

Step 2: Service Configuration

\n

Configure the external services required for your environment.

\n

MongoDB Database

\n

Your environment needs a MongoDB database. You can:

\n\n

Enter your connection details:

\n\n

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

\n

AWS S3 Storage

\n

File storage for images, documents, and backups.

\n

If you have AWS credentials with admin access:

\n\n

If you have existing AWS credentials:

\n\n

Brevo Email Service

\n

For sending transactional emails (password resets, notifications).

\n\n

Google Maps (Optional)

\n

For displaying walk routes and meeting point maps.

\n\n

OS Maps (Optional)

\n

For displaying Ordnance Survey maps.

\n\n

reCAPTCHA (Optional)

\n

For spam protection on public forms.

\n\n

Step 3: Admin User Setup

\n

Create the first administrator account for your new environment.

\n

Enter:

\n\n

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

\n

Step 4: Deployment Options

\n

Configure how your environment will be deployed.

\n

fly.io Deployment Settings

\n\n

Options

\n\n

Step 5: Review and Create

\n

Review all your configuration before creating the environment.

\n

The summary shows:

\n\n

Click Create Environment to start the provisioning process.

\n
\n

Environment Creation Progress

\n

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

\n
    \n

  1. Creating AWS Resources

    \n\n
    2. \n

  2. Initialising Database

    \n\n
    3. \n

  3. Deploying to fly.io (if selected)

    \n\n
    4. \n
\n

Each step shows:

\n\n

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

\n
\n

Managing Existing Environments

\n

Resume Setup

\n

If environment creation was interrupted:

\n
    \n
  1. Select "Manage Existing Environment"
    2. \n
  2. Choose your environment from the list
    3. \n
  3. Select "Resume Setup"
    4. \n
  4. Choose which steps to run:\n
    5. \n
\n

Update Environment

\n

Update an existing environment's configuration:

\n\n

Destroy Environment

\n

Permanently remove an environment and all its resources:

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

This will remove:

\n\n

Warning: This action cannot be undone.

\n
\n

Post-Setup Tasks

\n

After your environment is created:

\n

1. Access Your New Site

\n

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

\n

2. Log In as Admin

\n

Use the admin credentials you created during setup.

\n

3. Configure Site Settings

\n

Go to Admin > System Settings to:

\n\n

4. Import Walks Data

\n

The system can automatically sync walks from the Ramblers API:

\n\n

5. Customise Page Content

\n

Edit the default page content:

\n\n
\n

Troubleshooting

\n

"API Key validation failed"

\n\n

"Database connection failed"

\n\n

"AWS resource creation failed"

\n\n

"fly.io deployment failed"

\n\n

Resuming Failed Setup

\n

If creation fails partway through:

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

CLI Alternative

\n

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

\n

See the NGX Ramblers CLI Reference Guide in Technical Documents for:

\n\n

The CLI provides the same functionality with additional automation options.

\n"}