This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

This is a placeholder page that shows you how to use this template site.

This section is where the user documentation for your project lives - all the information your users need to understand and successfully use your project.

For large documentation sets we recommend adding content under the headings in this section, though if some or all of them don’t apply to your project feel free to remove them or add your own. You can see an example of a smaller Docsy documentation site in the Docsy User Guide, which lives in the Docsy theme repo if you’d like to copy its docs section.

Other content such as marketing material, case studies, and community updates should live in the About and Community pages.

Find out how to use the Docsy theme in the Docsy User Guide. You can learn more about how to organize your documentation (and how we organized this site) in Organizing Your Content.

1 - Instructor CLI

Installation

In order to install and use the instructor scioer-builder command line tool you must have python 3.7 or newer installed on your system. In addition to python you must also have Docker installed and running on your computer. Docker Buildx is optional dependency that is only required if you are planning on building multiple CPU architecture images. Buildx should be installed by default when Docker Desktop is installed or when the official Docker package is installed on Linux.

The easiest way to install the instructor command line tool is to install it from the pypi python registry:

Installation

pip install scioer-builder

Alternatively the builder has also been published as a docker image here. Which can be installed using docker pull scioer/automated-builder:latest.

Helpful Tips and Commands

Once the tool is installed the following are some helpful commands that can be used to build a custom course image.

  • Get help with the tool scioer-builder --help
  • Be prompted for the configuration values for a new course scioer-builder --interactive

Once all / most of your custom course content has been created, we would recommend that you run the first few builds with the following options, in addition to the ones to set the actual content:

  • Do not use the --push option, to ensure that the test versions don’t get published yet
  • Do not use the --multi-arch option, to make the build run faster for testing
  • Use --tag value of something like test-course:latest this should make it a little easier to differentiate the development versions from the real one that’s ready to be published. This should also help prevent the docker registry from accepting your image if you accidentally set the --publish option
  • Experiment with the different configuration options, specifically the --motd-file and the various wiki options.

Configuration Options

The scioer-builder command supports a large number of configuration options. Nearly all of them can be set either through flags that are passed to the command, or through prompts when running in interactive mode. There are no options that are required to be set in order for the tool to be used.

The main 4 components that can be configured are:

  • The Jupyter Notebooks content
  • Lectures content
  • The Wiki content
  • the resource itself

Jupyter Content

The Jupyter content can be set from a git repository by using the --jupyter-repo option and specifying either the https or ssh url to clone the repository. If the ssh option is used then the --key-file option must also be specified with a path to an unlocked ssh private key that has access to the repository. If the https option is used then either the repository must be public, or the credentials to get access must be encoded into the url.

Alternatively, the --jupyter-directory option can be used to load the notebooks from a local directory instead of from a remote git repository. These two options cannot be used at the same time.

Lectures Content

The lectures content can be loaded the same way as the Jupyter Content, by using the --lectures-repo or --lectures-directory options. However, loading the lectures content from a git repository has been deprecated because lecture files are typically too large to hold in a git repository. There plans (tracked in issue #81) to add support for loading lectures from other sources.

Wiki Content

The wiki content has the most configuration options available that can be used to configure it. The content must come from a git repository. That repository can be loaded over ssh (using the same --key-file as the rest of the repositories), or over https. If https is used credentials for the repository can be specified using the --wiki-git-user and --wiki-git-password options, but they are not needed if the repository is public.

The wiki also supports configuring additional attributes such as: a title, if comments are enabled, and the page navigation mode.

The Resource

There are a number of options that can be used to configure the resource its self. The main ones are --base which is used to specify the base image that the custom course should be built for. Currently, we maintain the following images that can be used to make course resources from:

The default --base image is for the java resource.

The --tag option is used to specify the name of the image, including the docker tag for the image that will be built. The default value is sci-oer/custom:latest, but you should make sure that the name you pick is in your namespace in the docker registry that is being used. If you are just building for local testing and not pushing to a remote registry then the name does not matter as much.

The --push option must be specified to actually push the built image to the registry once it has been built. We recommend that you do not enable this option at first to make sure that the initial image you build is correct and behaves as expected. In order to be able to push the image, you must already be authenticated with the registry by using the docker login command.

The auto builder supports building the custom resource for both amd64 (intel / AMD) and arm64 (arm / Apple Silicone). By default, it will only build for the current CPU architecture, because it is faster when building to test the resource. It can be built for both by specifying the --multi-arch option and having Docker Buildx installed and enabled.

The full list of options that are available can be found by using the scioer-builder --help command.

Examples

Non-Interactive Mode

The following code block demonstrates an example command that will build a course resource for an object-oriented course in java. It will set a custom course title, and will not include any lecture resources, instead the lectures will be served through a reverse proxy within that are hosted on example.com.

Non-interactive Building

scioer-builder \
  --jupyter-repo https://github.com/sci-oer/oo-course-tutorials.git  \
  --example https://github.com/sci-oer/oo-course-practice.git  \
  --wiki-git-repo https://github.com/sci-oer/oo-course-wiki.git \
  --wiki-title "Introduction to Object Oriented Programming with Java"  \
  --tag "scioer/oo-java:W23" \
  --base "scioer/java-resource:sha-62b706b" \
  --static-url "https://example.com"

Interactive Mode

In this next example several of the options will be set through the command line flags and some others can be set when promoted, such as the wiki title. This example will add multiple examples that will be copied into the resources practice problem directories.

Interactively set the title

scioer-builder \
  --verbose \
  --interactive \
  --example-dir /data/example1 \
  --example-dir /data/example2 \
  --wiki-git-repo https://github.com/sci-oer/c-course-wiki.git \
  --tag "my-resource:latest" \
  --base "scioer/c-resource:sha-ba6af63"
....
## Information about the wiki to be created.
Enter the title for the Wiki: <Enter the title for the wiki here>
....

Using Docker

The following example uses the builder installed via docker and not through pip. When building a custom resource using the docker image there are a few extra steps that are required. As you can see in the command bellow, when specifying the ssh key file that should be used, the path that is specific must be the path in the container and not the path to the ssh key on your host computer. Additionally, all of the files that are used by the builder must be passed into the container as mounted volumes using the -v docker option.

Using the Docker Image

docker run -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /Users/marshall/.ssh/id_rsa:/id_rsa:ro \
  -v /Users/marshall/examples:/data \
  scioer/automated-builder:latest \
  --verbose \
  --key-file "/rd_rsa" \
  --example-dir /data/example1 \
  --example-dir /data/example2 \
  --wiki-git-repo https://github.com/sci-oer/c-course-wiki.git \
  --tag "my-resource:latest" \
  --base "scioer/c-resource:sha-ba6af63"

Getting Help and Reporting Issues

If the auto builder is not behaving correctly more information about its status can be obtained by running the command with the --verbose or the --debug options. These need to be specified on the command line and can not be enabled from within the interactive mode prompts. We recommend first re-running the command in --verbose mode as debug will produce a lot of output and is probably best left for use when reporting an issue.

The best way to report an issue is to create a new Github Issue and be sure to include the command, debug output, a description of what went wrong, as well as a brief description about the expected behavior and how the system is set-up.

2 - Student CLI

Installation

In order to install and use the student scioer command line tool you must have python 3.7 or newer installed on your system. In addition to python you must also have Docker installed and running on your computer.

The easiest way to install the instructor command line tool is to install it from the pypi python registry:

Installation

pip install sci-oer

Getting started

The student command line tool is a wrapper around the docker command line to make it easier and less error-prone to run and maintain several scioer course resources.

The scioer --help or the scioer -h commands can be used to display a help message for the tool and to list all the commands that can be used. Each of the sub commands also accept the --help option to get more details about how they work.

Setting up a new Course

The first step to using a course resource is to get the name of the image from the instructor of the course. For our example we are going to be using the scioer/oo-java:W23 resource. Once you have the course that you want to setup you can run the scioer config command to setup the new course. The command will prompt you for:

  • the name of the course, you can call it whatever you want, the name will be normalized to remove some difficult characters (like spaces)
  • the docker image, this will be the one that the instructor gave you scioer/oo-java:W23
  • if you want to automatically check for new versions of the course resource when it starts, accepting the default of ’no’ is probably fine here
  • where the files for the course should be stored, by default this is on the desktop, but any directory can be used
  • if you want to use the default ports, you should say yes to this unless you have a good reason not to. If you say no you will be prompted to specify each port that will be used yourself

And that’s it, you now have the new course configured.

Configuring a Course

$ scioer config
What's the name of the course?: test-course
What docker image does the course use? [scioer/oo-java:W23]: scioer/oo-java:W23
Automatically fetch new versions [y/N]:
Where should the files for the course be stored? [/Users/marshall/Desktop/testcourse]:
Use the default ports [Y/n]:

Starting the Resource

To start a course run scioer start <course name>. This will install/fetch the latest version of the course resource (if that configuration option was set). It may take some time for the resource to start the first time. If you only have one course configured you do not need to specify the course name, it will automatically start the only course in the config file. If there is no course configured with the specified course name, then the names of all the configured courses will be printed and one can be selected interactively.

Starting a shell

To start a shell in a running course resource use the scioer shell <course name> command. If you only have one course configured you do not need to specify the course name, it will automatically get a shell in the only course in the config file.

Stopping the Resource

To stop a running course resource use the scioer stop <course name> command. If you only have one course configured you do not need to specify the course name, it will automatically stop the only course in the config file.

Advanced Usage

You can check the status of the currently configured courses by using the scioer status command. This will print the location of the configuration file, and the current state of all the course resources.

By default, the course resource will only publish its ports to be available from localhost on the host machine. This was done for security of the resource to prevent it from accidentally be available to any other computer on the local network. However, there are certain scenarios where this may be desirable, in these cases you can manually edit the configuration file, which can be found at ~/.scioer.yml and set the value public: to true. This change will take effect the next time the resource is started.

Getting Help and Reporting Issues

If the command line tool is not behaving correctly more information about its status can be obtained by running the command with the --verbose or the --debug options. We recommend first re-running the command in --verbose mode as debug will produce a lot of output and is probably best left for use when reporting an issue.

The best way to report an issue is to create a new Github Issue and be sure to include the command, debug output, a description of what went wrong, as well as a brief description about the expected behavior and how the system is set-up.