User Guide

User Guide

This section covers how to, as a user of the Automating Science Project system, run a simulation of the system on your local machine.

If you don't want to run your own copy, you can instead access the live one and jump straight to the Running an Experiment guide.

Dependency Installation

There are relatively few dependencies to install since Docker encapsulates them in containers.

Git

Git is code version management tool.

If you don't already have it installed, you can download it on the git website.

Docker

Docker is a utility that manages small virtual machine "containers."

To install it, follow the instructions on Docker's documentation.

You might encounter a permissions error on Windows mentioning not being part of the docker-users group. Directions to fix that can be found here.

WSL Error

To get Docker to work properly, you will need to install WSL. This may fail for Windows. In this case, check that virtualization is enabled in the BIOS.

Retrieve the Code

In a location of your choice in a drive with at least 1 GB of free space, use Git to clone the repo.

Your command will probably look like this:

git clone --recurse-submodules https://github.com/AutomatingSciencePipeline/Monorepo.git

Or this if you have ssh keys set up:

git clone --recurse-submodules [email protected]:AutomatingSciencePipeline/Monorepo.git

The --recurse-submodules can be omitted if you don't want to download a copy of the docs as well.

If cloning isn't working for some reason, you can download a zip from here instead. Note that, if you download a zip, Windows or antivirus programs may block you from running the code, in which case you will have to navigate various security dialogs to unblock it. It may also not have the correct line endings (CRLF vs LF) for your system.

Get the .env file(s)

The system keeps track of private keys (strings that act as passwords to various services) in a .env file. For security reasons, these cannot be publicly distributed with the rest of the code.

You can get a copy of our .env file from our private Discord in the #env-files channel. Note that you must already be a member of the Discord to open this link; contact us if you need access.

The file should be named exactly .env (no file name, file extension of env) and placed in the root folder of the repository.

Alternative: Set up your own .env file

TODO This section will provide an overview of the steps needed to set up a totally separate version of the project that does not need our .env file, in case the user doesn't want to be linked to our own hosted resources.

There is an .example.env file in the root of the repo that explains the purpose of each field.

Notes about what services will need to be set up:

• Firebase
  • Frontend code has the Firebase public key in it (which does not need to be securely stored)
  • Admin SDK key for the python backend code (secure)

Run the System Locally

Once you have the above taken care of, you can use Docker to spin up a copy of the system.

1. Open a terminal in Monorepo root folder (Monorepo/)
2. Run docker compose up --build
   • This will start up the Docker Compose for the production version of the project, which will locally host a backend, frontend, and database for you. As of Fall 2023 it does not host a Firebase instance for you, and the env file you got from the discord will point to the production firebase.
   • Optionally use the flag -d to detach it from the terminal window, which means Docker will keep running even when the terminal is closed.
   • If you see an error message like open //./pipe/docker_engine: The system cannot find the file specified you probably don't have Docker started.
   • The --build flag indicates it should build the containers from scratch. You can exclude this flag from future runs, but you should build again after pulling new code from the repo.
   • If this succeeds, the last message in the console should be similar to: glados-backend | Press CTRL+C to quit
   • If this fails, see the troubleshooting steps below
3. Go to http://localhost:3000 (or another address, if the command output reports a different url) in your browser
   • Because you're running the production version, pages should load nearly instantly. The developer version might take a bit to load.
4. Once on the site, sign up for an account or log in.

Now you are ready to run an experiment.

See the Running an Experiment guide.

Troubleshooting

You can view the logs or output of a specific docker container by clicking on its row in the Docker Desktop application.

Docker Startup

• Docker Engine not started

  • Fix: Docker Desktop probably isn't on; turn it on. If it is on, open the GUI to look for errors.
  • Error message like below:

  error during connect: this error may indicate that the docker daemon is not running: Get "http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.24/containers/json?all=1&filters=%7B%22label%22%3A%7B%22com.docker.compose.project%3Dglados-project%22%3Atrue%7D%7D": open //./pipe/docker_engine: The system cannot find the file specified.

• Docker Desktop perpetually stuck on "Docker Desktop is starting..."

  • See this stackoverflow post
  • Or this post
  • Or, try manually installing any WSL distribution (ex. Ubuntu, Alpine) through the Microsoft Store
  • Or, try turning off WSL support in optionalfeatures.exe and re-running the Docker Desktop installer so that it re-enables it itself (the approach from here)

• level=warning msg="The \"FIREBASE_KEY\" variable is not set. Defaulting to a blank string."

  • You need to obtain or set up a .env file as described in the section above.

• While building Docker, there might be an exception like this: Error response from daemon: status code not OK but 500: Unhandled exception: SQLITE_CONSTRAINT_UNIQUE (Exception from HRESULT: 0x87AF0813)

  • Go to Windows Docker Desktop App > Setting > Resources > File Sharing and add the directory that you have the MonoRepo.
  • Restart your Docker and rebuild it.
  • Check out this stackoverflow post

• After building the container, you might run into an error glados-mongodb exited with code 14 dependency failed to start: container glados-mongodb exited (14)

  • Go to the Docker Desktop application's Settings > General and check if "User the WSL 2 based engine" checkbox is checked (It should be enabled)

Shut Down your Local Copy

To stop the system, you must shut down the docker containers. There are a few ways to do this:

• In the repo root, run the command docker compose down
• If you did not use the -d flag when starting the docker compose, using Ctrl+C will shut down the compose and containers.
• Use the Docker Desktop user interface 'Stop' button on the collection

Correctly Close Docker

Docker is very convenient for modular systems and development, but unfortunately, it can be quite a memory hog. In Windows task manager, it will show up as Vmmem, since it's using the WSL2 backend.

Once you're done using it, make sure to 'Quit Docker Desktop' from the tray icon (Windows) when you're done to get your memory back.