HomeGuidesChangelog
GuidesDiscussionChangelogLog In

Manually Run a Project

Power users can use Docker directly to run a Project outside Gigantum

It is possible for power users to run a Project without using Gigantum. To do so, you must have already imported the Project locally using the Client and have access to all of its files.

On import, the Client will render the Dockerfile for you that can be used to build the image if needed. The Client will build the image for you, but if you remove it or move the Project to another system manually you will have to rebuild.

Note, when running manually all automatic versioning will not function and you will need to manage your changes yourself.

Build the Project's Docker Image

If you need to build the Project's image you can directly invoke Docker's build command. You should tag the image so you can easily use it later. Also you must determine the env directory of the Project. This directory is located at .gigantum/env relative to the Project's root. Review the Directly Access Files in Gigantum Projects or Datasets section for more details on how to find the Project root locally.

docker build -t <a name for your image> <path to env dir>

Example:

docker build -t my-project ~/gigantum/servers/gigantum-com/my-user/my-user/labbooks/test-project/.gigantum/env

When running this command, you may get the error message COPY failed: no source files were specified. This means that your were using custom Certificate Authority certs. The Client manages copying these certs into the Project's env directory before the build and then deletes them after to prevent leakage of these certs.

You can be sure your environment was configured like this if you see the following in the .gigantum/env/Dockerfile:

# Configure user provided CA certificates
COPY certificates/*.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

If you need to keep using the custom CAs, you must place the certs in the right location before building. To do this, create the directory .gigantum/env/certificates inside the Project and place all required certs there. You may find these in ~/gigantum/certificates. Then run the build command as shown above.

If you no longer wish to use the custom CA certs, you can simply remove the three Dockerfile instructions above.

Run the Project's Docker Container

To run a built Project container you must provide the proper environment variables and volume configuration due to the Client managing a lot for you.

First, get the UID of your local user account on your host. You can typically do this by running id -u <username> in your terminal (<uid> in the command below).

Determine the absolute path to the directory that contains the Project you wish to run (<project_path> in the command below).

Determine the image name to run. If you built manually as shown in the section above, this will be what ever you put after the -t flag. (<image_name> in the command below).

Finally you can run the following Docker command to start the container. In the example below the default jupyter port 8888 is used, but you could change this if you plan to run RStudio or a bundled app.

Note, if you are on Windows, you must add --env WINDOWS_HOST=1 to the command below.

docker run -it --env LOCAL_USER_ID=<uid> --mount type=bind,src=<project_path>,dst=/mnt/labbook --mount type=volume,target=/mnt/share -p 8888:8888 --name "my-project" <image_name> /bin/bash

This should drop you into the container as "giguser", which is a user with the same UID as your account on your host. This will make sure that files are edited with the correct permissions over the bind mount.

Finally without the Client's proxy in place you must start Jupyter and access it directly.
Run jupyter lab --port=8888 --ip=0.0.0.0. After it has started, open the displayed link that starts with http://127.0.01 in your browser.

If you used the Sensitive Files feature of the Client, you'll need to manually copy them into the running container. You can do that via a Docker command like this, where my-project is the name of the running container:

docker cp /path/to/file.txt my-project:/home/giguser/file.txt