Setting up a local development environment
This document covers the nuts and bolts of setting up a development environment, but be sure to review our main contribution page for more general information.
Prerequisites
You should have Node installed at v12.0.0+ and npm. If you want to work on the server, you will also need docker and docker-compose.
Installing dependencies
Run npm install
after cloning this repository.
How to add a Python dependency
Add new dependencies to the requirements template file requirements/build.in
and run make pip-compile
. This will regenerate the requirements/build.txt
file which will be used when building the Iodide server image.
Running/Building
Client-only mode
If you're only working on client code and don't need to use/test any of the server functionality described below,
you can skip setting up a full docker environment and get up and running quickly. Just run
npm run simple-serve
after npm install
: this should start up a web server which will provide a basic
version of the editing environment you can access at http://localhost:8000/.
The command runs in watch mode, so changes to files will be detected and bundled automatically, but you will need to refresh the page in your browser manually to see the changes -- we have disabled "hot reloading" because automatically refreshing the browser would cause any active notebooks to lose their evaluation state.
If you want to use another port number (e.g 9999
), you can use the command npm run simple-serve -- --port=9999
If you require verbose Redux logging, you can use the command REDUX_LOGGING=VERBOSE npm run simple-serve
Server mode
To develop or test server-side functionality like saving notebooks or authentication, you will need to set up a server environment using docker and docker-compose. Follow this set of steps:
- Register a GitHub oauth token. Set the homepage URL to be "http://localhost:8000" and the authentication callback URL to be "http://localhost:8000/oauth/complete/github/".
- Copy
.env-dist
to.env
and set theGITHUB_CLIENT_ID
andGITHUB_CLIENT_SECRET
to the values provided above. - Make sure you have Docker and Docker Compose installed and working correctly
- Run
make build && make up
- You should now be able to navigate to a test server instance at http://localhost:8000
On subsequent runs, you only need to run make up
.
Additionally, if you are working on client code, you can run npm run start
in a separate terminal to run webpack in watch mode (which will make your client code changes visible on page reload). If you require verbose Redux logging, you can set the environment variable REDUX_LOGGING=VERBOSE
with the command REDUX_LOGGING=VERBOSE npm run start
Sometimes, for debugging purposes, it is useful to have a shell session inside the "app" docker container. You
can use either the make shell
command (creates a shell session with the "app" user) or the make root-shell
commands (creates a shell session logged in as root, useful for experimenting with new python packages). Note that the iodide server environment must already be running for this to work.
Building the docs
The documentation is written in markdown, and uses mkdocs to generate a static website.
To test changes to the docs locally, you'll need to install mkdocs
and
markdown-include
. This is completely independent of the server's Docker image
described above. If you have pip
and python
installed on your system, you
can install these packages using the command:
pip install mkdocs markdown-include
If that doesn't work, consult the mkdocs installation instructions.
Then you can run:
mkdocs serve
to preview the docs during development.
To build a local, static copy of the docs, run:
mkdocs build
Testing
Iodide currently has two test suites, one written with jest to test the editor environment. Another written with pytest to test the server.
Editor unit tests (jest)
Run npm test
to run the test suite once, or npm test --watch
to run the suite in watch mode, which will automatically re-run the tests when the source or tests have changed.
Iodide server unit tests (pytest)
After bringing up the docker-compose environment (see above), run make shell
then py.test
to run the full test suite. You can run a small subset of the tests by specifying what you want on the command line. For example py.test server/tests/test_file_api.py
will only run the tests contained in that file.
Running with a local build of Pyodide
If you want to test your local changes to Pyodide with your local build of Iodide, there are instructions here.