Skip to content

Development Setup GitHub Codespaces

Jump to bottom Edit New page
jayto581 edited this page Oct 2, 2026 · 1 revision

Creating a Full FreeREG Development Environment on GitHub Codespaces Using a Web Browser

Rails 6.1 Version (2026-09-02)

Time Required: ~ 1 - 2 hours

GitHub Codespaces is a cloud based integrated development environment (IDE) similar to AWS Cloud9. It lets you write, run, and debug your code from any supported browser or code editor. You can work on your project from anywhere using an Internet-connected machine.

The browser interface uses a web version of Visual Studio Code (VS Code) and includes a code editor, file explorer, and terminal.

The main user interface components of VS Code are:

  1. Side bar
  2. Activity bar
  3. Editor
  4. Panels (Integrated Terminal)
  5. Status Bar

A codespace is a single development environment. You can customize your codespace by committing configuration files to your GitHub repository. These files define the environment setting for your project. Each codespace on GitHub is a Docker container running on a Linux virtual machine (VM).

Codespace is a paid service. However, individuals can use Codespaces for free each month for up to 120 hours with 15GB storage. After that, there's pay-as-you-go pricing. The free service is limited to 2 core and 4 core virtual machines.

  • Two core users will get 120 hours per month free for individuals
  • Four cores users will get 60 hours per month free for individuals

What You Need for Codespaces

  • A GitHub account
  • Chromium-based browsers (such as Chrome or Microsoft Edge). Mozilla Firefox not supported
  • Internet connection

Attention

  • When you delete a codespace environment, the source code and data are also deleted
  • If you delete your fork repository, then any codespaces linked to the fork are also be deleted, even if you originally created them from the upstream repository (ie FreeUKGen/MyopicVicar)
  • Development environments (VMs) in GitHub Codespaces are automatically deleted after 30 days of idle status
    • You will be notified by email in advance, but be sure to push the source code that you don't want to lose back to your repository.
  • A GitHub codespace VM also automatically shuts down after 30 minutes of inactivity by default
  • Once the VM is stopped you will no longer incur computing charges, but it will take some time to restart the VM
  • If you leave it running, you will continue to be charged so it's best to stop the VM when not in use

Requirements

  • A GitHub account
  • Supported browser
  • Internet connection
  • As a developer you will do most of your work with the test version of FreeREG. So it is essential you register on https://test.freereg.org.uk/
    • Authentication
      • username: test
      • password: test
    • Please register for the technical syndicate (test3)
    • You will need your user ID and password when you come to use the development system on Codespaces
  • Your mentor should have sent you a number of files that need to be installed in appropriate locations
    • If you have not got them ask for them
    • These files should never be committed to the GifHub repository

Table of Content

A. Launching GitHub Codespace 3

B. Setup Codespace Virtual Machine (VM) Configuration Folder 4

C. Upload FreeREG Codespace Configuration Files 5

D. Start FreeREG Codespace Virtual Machine 6

E. Upload MongoDB JSON Collection Files 7

F. Upload FreeREG CSV Data Files 8

G. Load Data Into Databases 8

H. Final Setup Step 9

I. Verify Everything is Working 9

J. When You are Finished Working on a Codespace Virtual Machine 10

K. Troubleshooting 10

L. References 12

  1. Launching GitHub Codespace {#launching-github-codespace}

  • Log onto your GitHub repository

  • Using the search box at the top of the GitHub dashboard find the desired repository

    • Type myopicvicar

  • Select the FreeUKGen/MyopicVicar repository

  • Create a fork of the FreeUKGen/MyopicVicar repository on to your GitHub account

  • Click the green Code button in middle of screen on your copy the MyopicVicar repository

    • Select Codespaces tab

    • Click "Create codespace on master"

  • Wait for the Codespace virtual machine to be created. This may take a few minutes

  • You will next setup the Codespace virtual machine configuration folder

  1. Setup Codespace Virtual Machine (VM) Configuration Folder {#setup-codespace-virtual-machine-(vm)-configuration-folder}

  • Access the VS Code Command Palette

    • Press F1 or
    • Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)

  • Type codespaces

  • Select "Add Dev Container Configuration Files..."

  • Select "Modify your active configuration..."

  • Press the escape (ESC) key to exit the "Select Features" process

    • You will be uploading a custom configuration

  • In the side bar/explorer pane on the left side of the screen, you will see the .devcontainer folder

  • Open the folder and you will see a devcontainer.json file

    • Select this file and right click, this will open the context menu, and select "Delete Permanently"

  • You should now have an empty .devcontainer folder

  • Next you will upload some files your mentor sent you into the .devcontainer folder

  1. Upload FreeREG Codespace Configuration Files {#upload-freereg-codespace-configuration-files}

  • In the side bar/explorer pane on the left side of the screen, right click the .devcontainer folder to open the context menu

    • Select "Upload"

    • Upload the following files sent to you by your mentor; these files are never committed to the GifHub repository (already in .gitignore)

      • .env.development
      • devcontainer.json
      • Dockerfile
      • fugsetup_all2b.sh
      • mongod

When you are finished your .devcontainer folder will look like the following: .devcontainer folder .env.development devcontainer.json Dockerfile fugsetup_all2b.sh mongod

  1. Start FreeREG Codespace Virtual Machine {#start-freereg-codespace-virtual-machine}

  • Modify the Environment Variables in .devcontainer/env.development file ( 1 of 3)
  • Set LOAD_DATA=none
    • This will setup the codespace VM with the correct operating system and software
  • Access the VS Code Command Palette
    • Press F1 or
    • Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)
  • Type codespaces
  • Select "Rebuild Container"
    • Confirm rebuild by clicking "Full Rebuild"
  • The full rebuild process will take up to 30 minutes or more (depending on Codespaces’ load)
macOS Upload Bug: Leading Dot Stripped from .env.development When uploading .env.development via the Codespaces file upload dialog on macOS, the leading dot can be silently stripped, resulting in a file named env.development instead. This causes container startup to fail with: docker: open .devcontainer/.env.development: no such file or directory. Codespaces will then silently fall back to a bare Alpine "recovery container" — not your FreeREG environment. Ruby, Rails, MySQL, and MongoDB will all be missing. Fix: 1. Check the actual filename: ls -la .devcontainer/ 2. If it uploaded as env.development (no dot), rename it: mv .devcontainer/env.development .devcontainer/.env.development 3. Full Rebuild Container (Command Palette → "codespaces" → "Rebuild Container" → confirm Full Rebuild) Prevention: After uploading any dotfiles on macOS, immediately verify with ls -la before rebuilding, don't assume the upload preserved the leading dot.

  • This will create the base FreeREG development environment with some folders needed for later setup steps

  • Wait until you see the prompt in the Codespaces terminal panel

Check Software Versions

$ ruby -v ruby 2.7.8p225 (2023-03-30 revision 1f4d455848) [x86_64-linux] $ rails -v Rails 6.1.7.10

  1. Upload MongoDB JSON Collection Files {#upload-mongodb-json-collection-files}

  • In the side bar/explorer on the left side of the screen, right click the tmp/collections folder to open the context menu
    • Select "Upload"
    • Upload the following files sent to you by your mentor; these files should never be committed to the GitHub repository
      • This will take about five minutes
        • places.json
        • countries.json
        • registers.json
        • syndicates.json
        • userid_details.json
        • denominations.json
        • counties.json
        • churches.json
        • emendation_rules.json
        • emendation_types.json
  • Make sure all the data files have been uploaded before going to the next step

  1. Upload FreeREG CSV Data Files {#upload-freereg-csv-data-files}

  • In the side bar/explorer on the left side of the screen, right click the tmp/datafiles/testuser4 folder to open the context menu
  • Select "Upload"
  • Upload the files sent to you by your mentor
When you are finished your tmp folder will look like the following: tmp/collections folder places.json countries.json registers.json syndicates.json userid_details.json denominations.json counties.json churches.json emendation_rules.json emendation_types.json tmp/datafiles/testuser4 folder fileA.csv fileB.csv . . .

  1. Load Data Into Databases {#load-data-into-databases}

  • Modify Environment Variables in .devcontainer/.env.development File (2 of 3)
    • Set LOAD_DATA=all
  • Rebuild Container
  • Access the VS Code Command Palette
    • Press F1 or
    • Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)
  • Type codespaces
  • Select "Rebuild Container"
  • Confirm rebuild by clicking "Rebuild"
  • Time for a cup a tea (it will take about 30 minutes or more to load the data)

  1. Final Setup Step {#final-setup-step}

  • Modify Environment Variables in .devcontainer/.env.development File (3 of 3)
  • Set LOAD_DATA=none
    • The codespace VM is now ready to use

  1. Verify Everything is Working {#verify-everything-is-working}

  • You should now have a working development version of FreeREG in Codespaces

  • In the panels/integrated terminal panel, load the FreeREG assets and start the Ruby on Rails web server with the following commands:

    • rails server
      • This will start the Rails web server

  • When the web server is running you will be prompted to open a browser

    • Click "Open in browser" and your default browser will open to the FreeREG home page

  • You should be able to run a search

    • Example search (four results found)
      • Last Name: durrant
      • Record Type: Marriage
      • County: Norfolk
      • Place: South Wootton

  • You should be able to login into the FreeREG application running on the rails server with user ID (testuser4) and password (testuser4) through the Members link

  • You are now ready to start coding

    • It is important to work on a different branch so that you do not affect other developers, yet at the same time share your code with them

    • See `Using source control in your codespace` for more information

      • Ignore the "Publishing a codespace created from a template" section as it does not apply in our case

      Using source control in your codespace - GitHub Docs

  • For more information about Codespaces see the reference section L

  1. When You are Finished Working on a Codespace Virtual Machine {#when-you-are-finished-working-on-a-codespace-virtual-machine}

  • Codespaces is a paid service
    • It is important to stop your VM when you are not using it so you do not incur computing charges
  • Access the VS Code Command Palette
    • Press F1 or
    • Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)
  • Type codespaces
  • Select "Stop Current Codespace"

  1. Troubleshooting {#troubleshooting}

  • If the development environment is not working properly, try the "Rebuild Container" option

    • This will clear the cache and reload the application software
    • The databases will not be affected by the rebuild process
    • This will take a few minutes to complete
    • You may need to try this more than once

  • If the development environment is still not working properly, try the "Full Rebuild Container" option

    • This will clear the cache, clear the database, and reload the operating system and application software
      • Be sure to modify the Environment Variables in .devcontainer/dev.env File
        • Set LOAD_DATA=none
    • This will take five or more minutes to complete
    • You will need to reload the data to the databases
      • See instructions for this in section G

  • error: E11000 duplicate key error collection error message

    • Data is already loaded in database
    • Be sure to modify the Environment Variables in .devcontainer/dev.env File
      • Set LOAD_DATA=none
    • You may need to do a "Full Rebuild Container" operation to reset the database

  • /etc/init.d/mongod: 139: ulimit: error setting limit (Operation not permitted)

    • These warnings do not impact the development environment and can be ignored

  • If you have trouble with the css

    • go to /config/environments/development.rb and make sure the setting config.assets.compile is set to true

  1. References {#references}

Creating a codespace for a repository
https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository

Opening an existing codespace
https://docs.github.com/en/codespaces/developing-in-a-codespace/opening-an-existing-codespace

Developing in a codespace
https://docs.github.com/en/codespaces/developing-in-a-codespace/developing-in-a-codespace

Using source control in your codespace
https://docs.github.com/en/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace?tool=webui

Using the Visual Studio Code Command Palette in GitHub Codespaces
https://docs.github.com/en/codespaces/reference/using-the-vs-code-command-palette-in-codespaces

Troubleshooting GitHub Codespaces
https://docs.github.com/en/codespaces/troubleshooting

© 2025 FreeUKGen. Licensed under Apache License 2.0

Clone this wiki locally