{"id":20082181,"url":"https://github.com/exercism/development-environment","last_synced_at":"2025-06-12T11:06:06.965Z","repository":{"id":39863316,"uuid":"283798136","full_name":"exercism/development-environment","owner":"exercism","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-01T14:06:20.000Z","size":146,"stargazers_count":16,"open_issues_count":6,"forks_count":19,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-25T18:22:26.257Z","etag":null,"topics":["community-contributions-paused"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exercism.png","metadata":{"funding":{"github":["exercism"],"custom":["https://exercism.org/donate"]},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-07-30T14:32:03.000Z","updated_at":"2024-01-16T18:45:10.000Z","dependencies_parsed_at":"2024-03-01T15:25:57.871Z","dependency_job_id":"fd8769c4-b695-457a-b1db-865d0450bef8","html_url":"https://github.com/exercism/development-environment","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exercism%2Fdevelopment-environment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exercism%2Fdevelopment-environment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exercism%2Fdevelopment-environment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exercism%2Fdevelopment-environment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exercism","download_url":"https://codeload.github.com/exercism/development-environment/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exercism%2Fdevelopment-environment/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":257143975,"owners_count":22496290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["community-contributions-paused"],"created_at":"2024-11-13T15:42:17.864Z","updated_at":"2025-06-12T11:06:01.940Z","avatar_url":"https://github.com/exercism.png","language":"Ruby","funding_links":["https://github.com/sponsors/exercism","https://exercism.org/donate"],"categories":[],"sub_categories":[],"readme":"**NOTE: This repository is part of the lastest version of Exercism, v3. It is not applicable for the older versions of Exercism.**\n\n---\n\n# Exercism Development Environment\n\nHello! 👋\n\nThis repository will provide you with Exercism's local development environment, which you can use to develop any part of the project.\n\nOur aim is to get you to a working setup within 10 minutes from now, most of which will be spent downloading things, but if you have a slower internet connection, things may take longer.\n\nIt requires the following to install:\n\n- **[Docker](https://docs.docker.com/get-docker/):** Docker needs to be installed but **no Docker knowledge is required** and you do not need a DockerHub account.\n- **[Ruby](https://www.ruby-lang.org/en/documentation/installation/):** Many of the scripts in this repository are written in Ruby. Any version 2+ is fine.\n- **Git:** In order to obtain this repository using the instructions below, you need `git` installed.\n\n**Windows users:** We recommend using [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) and running the commands in a WSL-enabled terminal.\n\n**Updates:** We have a [Changelog](./CHANGELOG.md) which lists breaking changes with instructions to follow to ensure your development environment continues to work.\nPlease check it reguarly.\n\n## Basic setup\n\nThe following instructions take you through getting the most basic setup working.\nWe'll explain what actually happens below the hood, and how to configure things afterwards.\n\n### Update hosts file\n\nAs the website is expected to run at `local.exercism.io`, you should update your hosts file to have `local.exercism.io` resolve to `127.0.0.1` (localhost).\n\n### Getting set up\n\nTo start, run the following instructions line-by-line:\n\n```bash\n# Make a directory to host all of Exercism within\nmkdir exercism\n\n# Move into the new directory\ncd exercism\n\n# Clone this repository onto your computer\ngit clone git@github.com:exercism/development-environment.git\n\n# Move into the new directory\ncd development-environment\n\n# Create your \"stack\" - the collection of parts of Exercism you\n# want to run locally. To start with, copy the default file.\ncp stack.default.yml stack.yml\n\n# Start everything\n./bin/start\n```\n\nOnce the script has finished, the website will be running at http://local.exercism.io:3020.\n\n### Updating everything\n\nThe first time `./bin/start` is run, it will download the latest versions of all the Exercism components for you to use.\nIf you want to download and run the latest version of those components — which we advise doing regularly — run:\n\n```bash\n./bin/start --pull\n```\n\nIf you face any issues getting started, we recommend running this step in case anything is cached locally from a previous installation.\n\n### Logs\n\nOnce the docker stack is running you can view the logs in real-time using:\n\n```bash\ndocker-compose logs -f\n```\n\nYou can watch the logs of a single component by specifying its name.\nFor example, to tail the `website` logs:\n\n```bash\ndocker-compose logs -f website\n```\n\nIt is also possible to have container logs be output to the console. To enable this, pass the `--tail` argument to `./bin/start`:\n\n```bash\n./bin/start --tail\n```\n\n### Shelling into a component\n\nYou may want to access a shell on a running component to run commands or check what is going on.\nTo access a shell on a running container you can use the provided `bin/shell` command.\nFor example, to shell into the running `website` container, you would run:\n\n```bash\nbin/shell website\n```\n\n### Stopping everything\n\nTo stop everything, run:\n\n```bash\ndocker-compose stop\n```\n\nAlternatively, to stop everything _and_ remove all data (including the database storage), run:\n\n```bash\ndocker-compose down\n```\n\nDetails for restarting individual components are explained below.\n\n## What is actually going on?\n\n### Docker Compose\n\nWe are using [Docker Compose](https://docs.docker.com/compose/).\nCompose is a tool for defining and running applications made up of multiple [Docker containers](https://www.docker.com/resources/what-container).\nWith Compose, you use a YAML file to configure your application’s services.\nThen, with a single command, you create and start all the services from your configuration.\n\nIn the context of Exercism, each component (e.g. the website UI, an analyzer, the code that manages test runners) has it's own Dockerfile.\nThese Dockerfiles are stored within each component's repository (often named `dev.Dockerfile`) and are built and pushed to DockerHub via GitHub Actions.\n\nThe code in this repository handles the creation of a `docker-compose.yml` and provides you with some wrapper scripts to run things.\nThe `bin/start` script generates the `docker-compose.yml` by merging your local `stack.yml` file with [docker-compose-full.yml](docker-compose-full.yml).\nIt then downloads the images from DockerHub (if missing locally) and starts them via `docker-compose up`.\n\nRunning with `--pull` checks DockerHub for updated images. Running with `--build` rebuilds any Dockerfiles where the have `build: true` set in `stack.yml`\n\nNote: Docker for Windows by default stores its data on the `C:` drive, but this can be changed in the settings.\n\n### stack.yml\n\nThe `stack.yml` file is a Exercism-specific configuration file that allows you to select which components you want to run locally, and any configuration you want to do.\nThe `bin/start` script then takes that configuration and does the work of turning it into a `docker-compose.yml`.\n\nEvery Docker image you download takes up storage space, and every docker container you run takes up memory, so the `stack.yml` file allows to you ensure that you only run the things that are necessary for whichever part of Exercism you are working on.\n\n## Advanced Usage\n\n### Working on certain components of the architecture\n\nIn order to working on a specific component of Exercism's architecture, you will need to have the relevant git repository downloaded locally. For example, if you wanted to work on the `javascript-test-runner`, you might do the following:\n\n```bash\n# Start in your general Exercism directory (the first you made in the instructions above)\ncd exercism\n\n# Clone the relevant repository\ngit clone git@github.com:exercism/javascript-test-runner.git\n```\n\nThe next step is to navigate to the `development-environment` directory:\n\n```bash\n# Move into the directory for *this* repo\ncd development-environment\n```\n\nNow edit the `stack.yml` file to both enable the component and set its `source` configuration option to `true`:\n\n```yaml\n# stack.yml\n\nenabled:\n  - javascript-test-runner\n\nconfigure:\n  javascript-test-runner:\n    source: true\n```\n\nRunning `./bin/start` will now mount the locally checked out repository in the Docker container.\nThis means any changes you make to the local filesystem are reflected within the Docker container.\n\nDepending on the reload-behaviour of the component you are working, you may need to restart the component after changes.\nFor example, the Website live-updates any changes made to the code as Rails applications and designed to do so, but the Tooling Invoker does not as it is a more simple Ruby application.\nRestarting a component can be achieved by running a single command:\n\n```bash\ndocker-compose restart tooling-invoker\n```\n\n### Manually building docker images\n\nIn more unusual situations you may need to (re)build the docker image from source, rather than using a pre-provided image.\nThis is especially true if you're planning on modifying the dependencies (local libraries, node modules, gems, dependencies, etc), as opposed to just changing source code.\nDependencies are usually \"baked\" into the images at build time.\n\nTo rebuild an image from source, edit the `stack.yml` to include a `build` section for the component you want to build from source.\n\nFor example, to have the tooling-invoker build from source rather than using an image:\n\n```yaml\n# stack.yml\n\nconfigure:\n  tooling-invoker:\n    build: true\n```\n\nAnd then, to build it:\n\n```bash\n./bin/start --build\n```\n\nEach time you change the Dockerfile or dependencies it mounts (e.g. the Gemfile), you will need to rerun the start command with the `--build` flag.\n\n### Customizing Git integration\n\nThe development environment uses the track repositories (e.g. [Ruby](https://github.com/exercism/ruby)) as its source for track contents, such as its exercises, concepts and documentation.\n\nIf you are using the development environment to work on a specific track, you can instruct the website to use a specific repository (e.g. a local fork) rather than downloading the default repositories from GitHub.\nCurrently, the database seeds contain only the Ruby track, so accessing your track's content via the Ruby track links/URLs is the easiest way to load your track's data to the local website (e.g. http://local.exercism.io/tracks/ruby)\nAdditionally, if you do seed/instantiate other tracks, they will all be associated with the `GIT_CONTENT_REPO` that you specify.\nAt some point in the future, the dev env will be upgraded to allow you to specify a repo for any track (and only that track).\n\nThese are three environment variables you can specify in your `stack.yml` that are used to customize the Git integration for the `website` component:\n\n- `GIT_CONTENT_REPO`: the Git repository to clone. You can use this to clone a fork (e.g. `https://github.com/me/go`) or a repository on the `website` container filesystem (e.g. `file:///usr/me/go`). If not specified, track repositories (e.g. `https://github.com/exercism/ruby`) are used.\n- `GIT_CONTENT_BRANCH`: the branch to checkout after cloning. If not specified, `main` is used.\n- `GIT_DOCS_BRANCH`: the branch to checkout after cloning the docs. If not specified, `main` is used.\n- `GIT_ALWAYS_FETCH_ORIGIN`: indicates if a `git fetch` runs each time information is retrieved from Git. If not specified, `true` is used.\n\nHere is an example:\n\n```yaml\nwebsite:\n  environment:\n    GIT_CONTENT_REPO: \"https://github.com/me/go\"\n    GIT_CONTENT_BRANCH: \"my-branch\"\n    GIT_ALWAYS_FETCH_ORIGIN: false\n    # Other environment variables ...\n```\n\nIf you use a repo on the `website` container's filesystem, you still need to commit your changes for them to be picked up by the website.\nYour branch will also need to match the `GIT_CONTENT_BRANCH` from above.\nOnly code and README changes will be picked up after committing.\nIf you need to make changes to the directory structure (like adding an exercise)\nand/or `config.json`, you will need to use the following commands to rebuild\nyour environment:\n\n```bash\ndocker-compose --remove-orphans down\nrm -rf tmp/exercism/*\nbin/start --pull\n```\n\n### Working with teams\n\nThe development environment keeps track of its teams in the https://github.com/fake-exercism organization, to prevent mutations to the actual Exercism teams.\nIf you'd like to use your own organization, specify the `GITHUB_ORGANIZATION` environment variable for the `website` component in your `stack.yml` file.\n\nHere is an example:\n\n```yaml\nwebsite:\n  environment:\n    GITHUB_ORGANIZATION: \"my-exercism-test-org\"\n    # Other environment variables ...\n```\n\n## FAQs?\n\n### Do I have to use this to work on Exercism?\n\nNo.\n\nIf you want to only work on a language track, without seeing it running in context of the website, you can just directly work on that repository. In fact, that is the most common way to work on tracks.\n\nSimilarly if you want to work on tooling (test runners, analyzers, representers, etc) and you are happy to develop them in isolation, you do not need to use this repository. Although you may choose to to see your work running in the context of the website.\n\nIf you want to work on the various components of the website itself, then this is the official and only-supported way to work. However, you do not have to use it. You **can** set things up and get things playing nicely together locally, but this will probably be challenging, and unlikely to be worth the investment of your time. Instructions for each component can be found in the individual repositories, but we do not maintain instructions on how to piece them altogether.\n\n### I'm on Mac and I get an error about Ruby\n\nMac OSX comes with a system ruby pre-installed. That can cause problems when using this, or other Ruby applications. If you're on Mac, and get one of the following errors, checkout [this troubleshooting issue](https://github.com/exercism/development-environment/issues/30)\n\n```\n/System/Library/Frameworks/Ruby.framework/Versions/3.1/usr/bin/ruby: bad interpreter: No such file or directory\n\nERROR: While executing gem ... (Gem::FilePermissionError)\nYou don't have write permissions for the /Library/Ruby/Gems/3.1.0 directory.\n\nError: The following directories are not writable by your user:\n/usr/local/lib\n```\n\n### I'm on Mac and the site doesn't load and/or is super slow\n\nThere are two likely scenarios here. The first thing to do is just wait longer.\nAfter running `bin/start --pull`, node may take 10 minutes or more to compile all of the javascript and css.\nIf this fails, make sure you have allocated at least 8GB of memory to your docker containers (sorry `¯\\_(ツ)_/¯`).\n\nSecondly, if you have mounted a git repo from your local filesystem, the Docker for Mac project has multiple long standing issues with mount performance.\nThey are (hopefully) [working on them](https://github.com/docker/roadmap/issues/7).\nThe best option is to shell into the website container and manually clone your repo there:\n\n```bash\nbin/shell website\ngit clone https://github.com/exercism/go.git /usr/src/go\n```\n\nKeep in mind, you'll need to re-run this step whenever you do a `docker-compose down`.\nIt may be preferable to edit code on your local machine and push up to github in order to see your changes.\nWe realize that neither option is ideal and we will work on making the development experience better as V3 becomes more mature.\n\n## Stuck?\n\nStuck running the Docker setup? Please open an issue in this repository, and we will try and help you fix things, and tweak things so other people don't face the same challenge.\n\nIf you have an issue unrelated to this local Docker setup, please open an issue in the relevant repository (e.g. for the JavaScript Test Runner, use https://github.com/exercism/javascript-test-runner).\nIf you are unsure where to open the issue, please use https://github.com/exercism/exercism.\n\n## Contributing to this repository\n\nWe welcome contributions! Please open an issue explaining the problem(s) you are facing, or put together a Pull Request demonstrating your idea or solution. Thank you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexercism%2Fdevelopment-environment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexercism%2Fdevelopment-environment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexercism%2Fdevelopment-environment/lists"}