NOTE: This repository is part of the lastest version of Exercism, v3. It is not applicable for the older versions of Exercism.
Hello! 👋
This repository will provide you with Exercism's local development environment, which you can use to develop any part of the project.
Our 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.
It requires the following to install:
- Docker: Docker needs to be installed but no Docker knowledge is required and you do not need a DockerHub account.
- Ruby: Many of the scripts in this repository are written in Ruby. Any version 2+ is fine.
- Git: In order to obtain this repository using the instructions below, you need
gitinstalled.
Windows users: We recommend using WSL2 and running the commands in a WSL-enabled terminal.
Updates: We have a Changelog which lists breaking changes with instructions to follow to ensure your development environment continues to work. Please check it reguarly.
The following instructions take you through getting the most basic setup working. We'll explain what actually happens below the hood, and how to configure things afterwards.
As 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).
To start, run the following instructions line-by-line:
# Make a directory to host all of Exercism within
mkdir exercism
# Move into the new directory
cd exercism
# Clone this repository onto your computer
git clone [email protected]:exercism/development-environment.git
# Move into the new directory
cd development-environment
# Create your "stack" - the collection of parts of Exercism you
# want to run locally. To start with, copy the default file.
cp stack.default.yml stack.yml
# Start everything
./bin/startOnce the script has finished, the website will be running at http://local.exercism.io:3020.
The first time ./bin/start is run, it will download the latest versions of all the Exercism components for you to use.
If you want to download and run the latest version of those components — which we advise doing regularly — run:
./bin/start --pullIf you face any issues getting started, we recommend running this step in case anything is cached locally from a previous installation.
Once the docker stack is running you can view the logs in real-time using:
docker-compose logs -fYou can watch the logs of a single component by specifying its name.
For example, to tail the website logs:
docker-compose logs -f websiteIt is also possible to have container logs be output to the console. To enable this, pass the --tail argument to ./bin/start:
./bin/start --tailYou may want to access a shell on a running component to run commands or check what is going on.
To access a shell on a running container you can use the provided bin/shell command.
For example, to shell into the running website container, you would run:
bin/shell websiteTo stop everything, run:
docker-compose stopAlternatively, to stop everything and remove all data (including the database storage), run:
docker-compose downDetails for restarting individual components are explained below.
We are using Docker Compose. Compose is a tool for defining and running applications made up of multiple Docker containers. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.
In the context of Exercism, each component (e.g. the website UI, an analyzer, the code that manages test runners) has it's own Dockerfile.
These Dockerfiles are stored within each component's repository (often named dev.Dockerfile) and are built and pushed to DockerHub via GitHub Actions.
The code in this repository handles the creation of a docker-compose.yml and provides you with some wrapper scripts to run things.
The bin/start script generates the docker-compose.yml by merging your local stack.yml file with docker-compose-full.yml.
It then downloads the images from DockerHub (if missing locally) and starts them via docker-compose up.
Running with --pull checks DockerHub for updated images. Running with --build rebuilds any Dockerfiles where the have build: true set in stack.yml
Note: Docker for Windows by default stores its data on the C: drive, but this can be changed in the settings.
The 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.
The bin/start script then takes that configuration and does the work of turning it into a docker-compose.yml.
Every 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.
In 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:
# Start in your general Exercism directory (the first you made in the instructions above)
cd exercism
# Clone the relevant repository
git clone [email protected]:exercism/javascript-test-runner.gitThe next step is to navigate to the development-environment directory:
# Move into the directory for *this* repo
cd development-environmentNow edit the stack.yml file to both enable the component and set its source configuration option to true:
# stack.yml
enabled:
- javascript-test-runner
configure:
javascript-test-runner:
source: trueRunning ./bin/start will now mount the locally checked out repository in the Docker container.
This means any changes you make to the local filesystem are reflected within the Docker container.
Depending on the reload-behaviour of the component you are working, you may need to restart the component after changes. For 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. Restarting a component can be achieved by running a single command:
docker-compose restart tooling-invokerIn more unusual situations you may need to (re)build the docker image from source, rather than using a pre-provided image. This 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. Dependencies are usually "baked" into the images at build time.
To rebuild an image from source, edit the stack.yml to include a build section for the component you want to build from source.
For example, to have the tooling-invoker build from source rather than using an image:
# stack.yml
configure:
tooling-invoker:
build: trueAnd then, to build it:
./bin/start --buildEach 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.
The development environment uses the track repositories (e.g. Ruby) as its source for track contents, such as its exercises, concepts and documentation.
If 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.
Currently, 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)
Additionally, if you do seed/instantiate other tracks, they will all be associated with the GIT_CONTENT_REPO that you specify.
At 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).
These are three environment variables you can specify in your stack.yml that are used to customize the Git integration for the website component:
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 thewebsitecontainer filesystem (e.g.file:///usr/me/go). If not specified, track repositories (e.g.https://github.com/exercism/ruby) are used.GIT_CONTENT_BRANCH: the branch to checkout after cloning. If not specified,mainis used.GIT_DOCS_BRANCH: the branch to checkout after cloning the docs. If not specified,mainis used.GIT_ALWAYS_FETCH_ORIGIN: indicates if agit fetchruns each time information is retrieved from Git. If not specified,trueis used.
Here is an example:
website:
environment:
GIT_CONTENT_REPO: "https://github.com/me/go"
GIT_CONTENT_BRANCH: "my-branch"
GIT_ALWAYS_FETCH_ORIGIN: false
# Other environment variables ...If 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.
Your branch will also need to match the GIT_CONTENT_BRANCH from above.
Only code and README changes will be picked up after committing.
If you need to make changes to the directory structure (like adding an exercise)
and/or config.json, you will need to use the following commands to rebuild
your environment:
docker-compose --remove-orphans down
rm -rf tmp/exercism/*
bin/start --pullThe development environment keeps track of its teams in the https://github.com/fake-exercism organization, to prevent mutations to the actual Exercism teams.
If you'd like to use your own organization, specify the GITHUB_ORGANIZATION environment variable for the website component in your stack.yml file.
Here is an example:
website:
environment:
GITHUB_ORGANIZATION: "my-exercism-test-org"
# Other environment variables ...No.
If 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.
Similarly 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.
If 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.
Mac 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
/System/Library/Frameworks/Ruby.framework/Versions/3.1/usr/bin/ruby: bad interpreter: No such file or directory
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/3.1.0 directory.
Error: The following directories are not writable by your user:
/usr/local/lib
There are two likely scenarios here. The first thing to do is just wait longer.
After running bin/start --pull, node may take 10 minutes or more to compile all of the javascript and css.
If this fails, make sure you have allocated at least 8GB of memory to your docker containers (sorry ¯\_(ツ)_/¯).
Secondly, if you have mounted a git repo from your local filesystem, the Docker for Mac project has multiple long standing issues with mount performance. They are (hopefully) working on them. The best option is to shell into the website container and manually clone your repo there:
bin/shell website
git clone https://github.com/exercism/go.git /usr/src/goKeep in mind, you'll need to re-run this step whenever you do a docker-compose down.
It may be preferable to edit code on your local machine and push up to github in order to see your changes.
We realize that neither option is ideal and we will work on making the development experience better as V3 becomes more mature.
Stuck 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.
If 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). If you are unsure where to open the issue, please use https://github.com/exercism/exercism.
We 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!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent