A Powershell script that guides a user through your project's Docker images
The primary purpose of Docker is to provide a testing environment for software developers. Therefore, the terminology used in the application and documentation is aimed at developers. Thus, using Docker can be quite frustrating for users without development experience.
On the other hand, there are cases where Docker can also be interesting for users without development experience. For example, if a software does not offer executable files for Windows, Docker offers the possibility to use this software on this operating system as well.
A few years ago, SageMath offered binaries for Windows built with Cygwin (see for example this page). Currently, the only way to work with SageMath on Windows is using the Windows Subsystem for Linux (WSL), which also requires some affinity for development.
Projects Docker Guide is designed to fill this gap. It helps a user install Docker for Powershell and then walks him through using the Docker images offered by your project. The current implementation assumes that this project is SageMath, but project-specific settings are separated from the general code so they can be easily adapted to other cases.
Please note that this is a pre-release version. Use at your own risk.
Download sagemath_docker_guide-installer. Open your download folder and mark the downloaded file. Open the context menue by clicking the right mouse key. Select Run with Powershell:
If you're asked if you want to agree to open the file, just do so! If that doesn't work, open a Powershell terminal (i.e. press the Windows key, type "powershell" in the search box, and launch the suggested app). Run the following code there:
Set-ExecutionPolicy Bypass -Scope Process -Force
.\Downloads\sagemath_docker_guide-0.2-installer.ps1
This assumes that you have downloaded the installer to your default Downloads folder. You will also need to replace the version number with the current one. If you get the following screen, answer "Yes":
If the installation was successful, you should see a SageMath icon (labeled SageMath Docker Guide) on your desktop. Simply click on the icon to launch the application.
After you have clicked on the SageMath Docker Guide icon the following will happen:
If you already have Docker for Powershell on your computer, you can skip this section. Alternatively (for advanced users), if you have a WSL-distribution (say Ubuntu or something similar) with a working Docker or if you have Docker Desktop you may skip this section, too.
If you don't have any Docker installed yet, you'll see the following screen:
After you accept to start the installation, the following hint will appear:
Docker for Powershell needs the Windows Subsystem for Linux (WSL). If this is present on your system you may skip this section. If not the installer tries to set this up.
During the process you must grant the following permissions:
After the installation of WSL is finished you have to reboot your computer:
If your computer is up again, click on the SageMath Docker Guide icon once more to continue the installation of Docker for Powershell. In rare cases you will see a screen like this:
This most likely happens if your CPU virtualization technology is not enabled in your BIOS setup. In this case, try to find help on this site.
Go back to the Table of Contents
If Docker starts automatically when you boot your computer, you can skip this section. If the Docker daemon is not already running, you will see the following screen:
Click Retry until the popup message disappears.
Go back to the Table of Contents
If you already have downloaded SageMath from Docker hub, you can skip this section.
If you don't have, you will see the following screen:
The first line takes you to the stable software versions of SageMath, the second to pre-release versions that do not guarantee that SageMath will run stable. The other lines are intended for advanced users. After selecting the desired line, press the OK button. You can also use the up and down arrow keys to select a line and then press Enter. A new window will open with the available software versions that you can download:
Again select the line of your choice and press OK. The download progress will be displayed in a separate window.
Depending on the quality of your internet connection, this may take some time. If you interrupt it, it will resume from where you interrupted it when you restart the SageMath Docker Guide as in this eaxmple:
Go back to the Table of Contents
If you have already created a session, you can skip this section.
If not, after starting SageMath Docker Guide you will see a list of software versions you have downloaded before (following the former section):
Select one of these entries and press the OK button. If the software was downloaded from a repository that offers multiple apps (as can be seen in the last column of the List of software that can be downloaded window in the previous section), you will need to select an app in the next window:
After that, or if you don't need to select the app, you will be shown a List of sessions that have been created or used formerly:
The naming scheme of the sessions is as follows: It starts with a prefix according to the app:
S-is the standard type of session. Here you can work with Sage in an IPython terminal.N-is the notebook type of session. Here you can work with Sage in a Jupyter notebook in your default browser.L-is the lab type of session (not supported yet). Here you can work with Sage in a Jupyter lab in your default browser.B-is the bash type of session. Here you can work in a bash terminal in which you can start SageMath by callingsage.
The prefix is followed by a part that points to the folder you can access while working with SageMath. By default, this is your home directory. You can change this in the SageMath Docker Guide icon settings in the Working Directory field, for example by changing %HOMEDRIVE%%HOMEPATH% to %HOMEDRIVE%%HOMEPATH%\sage if you prefer to work in a subfolder sage of your home directory.
If you have more than one directory for your SageMath work, you should create according copies of the icon.
The last part of the name is just a sequential number.
Go back to the Table of Contents
When you see the List of sessions ... window, you are ready to start working with SageMath. Simply select the session you want to connect and press OK.
If the session name is prefixed with "S-", a new terminal will open at the Sage prompt. Follow the SageMath documentation to use SageMath.
The SageMath functions load and save give you access to your Windows folder according to the session name (see previous section).
In SageMath you can use ls to view the files in your folder. In the case of the screenshot this is C:\Users\sebastian
Go back to the Table of Contents
If the session name is prefixed with N-, a new tab titled Home will open in your default browser, displaying the list of files in your folder. If this is the first time connecting to the session, this may take a few seconds.
The notebook provides special features for some of the files you already have there, but the most important file type for working with the notebook are those with the .ipynb extension. A handy way to learn more about SageMath notebooks is to download a relevant tutorial file, for example sage_tutorial. In the example in the screenshot, it was downloaded to the default Download folder. If you click on that folder on the Home tab, the file will appear there.
If you select it and then click Open, a new tab will open displaying the notebook.
The cells of it can be executed by the play button. All cells containing Sage code are executed with the version of SageMath for which the session has been created (in this case 10.4). If you want to create your own notebook, go back to the Home tab, click on New and select the line containing the version of SageMath for which this session has been created:
A new tab will open with the title Untitled. If you like, write some SageMath code in the first cell and press the Play button to see if it works:
Give your new notebook a name using the Save Notebook As entry in the File menu:
For more information on using Jupyter notebooks, see their documentation.
Go back to the Table of Contents
Sessions prefixed with B- require some experience with Linux operating systems. This session type is automatically set for repositories other than sagemath/sagemath:
These sessions open a bash terminal where you can start SageMath by typing sage and then pressing Enter. After that, it is similar to an S- session (see section 2.5.1). The main difference is that the terminal does not close when you exit SageMath by typing quit or exit. This takes you back to the bash prompt.
The advantage of this session type is that you can experiment with the SageMath library code. If your session belongs to the sagemath/sagemath-dev repository, you will find the code under /home/sage/sage/src/sage (as you can see in the screenshot above). If you make changes to Python files (extension .py), they will take effect immediately after restarting SageMath. Changes to Cython files (extension .pyx) require compilation, which can be done with sage -b (or sage -br to automatically start SageMath after compilation). For more information about SageMath development, see the Developer Information Page and the Developer Guide.
Any code changes you make in a B- session persist after you close the session. They remain until you delete the session (or manually undo it).
Go back to the Table of Contents
Your sessions don't take up much space on your computer, but you may still want to get rid of them, perhaps because they use an older version of SageMath that you no longer need.
To delete a session, simply select the Delete session line in the List of sessions that have been created or used formerly window. A new window will open showing all the sessions that can be deleted. You can also select multiple lines here.
After pressing OK, all selected sessions are deleted. Note that a session contains data that is not stored in your working directory. This data is lost when the session is deleted. This data is:
- The history data at the Sage prompt or in the notebook cell that you reach using the up and down arrow keys.
- Optional packages that you installed according to section 3.
- Intermediate results of time-consuming calculations that were automatically saved to disk to save time when this intermediate result is used more than once (file cache).
- Code changes that you made in a
B-session (see 2.5.3)
Go back to the Table of Contents
If you want to delete a software version that you no longer use, you can do so as follows: First, in the List of sessions that have been created or used formerly window, select the Create new session option. In the List of software that have been downloaded formerly window, select the Delete software line. The following window will then open:
In the example above, we want to delete sagemath\sagemath:10.5.beta5. You can use a multi-line selection in this window. However, it is not possible to delete a software if there is still a session using it. In such a case, the following window opens:
If you really want to delete the software, you need to select all the lines that appear there and press OK. Then you need to navigate again to the window that allows you to remove the software (as described above). Now, if you try it a second time, you will see a screen like this which confirms that the software has been removed:
Go back to the Table of Contents
SageMath provides a large list of optional extensions. Depending on what you want to do, it may be necessary to add such an extension to your session. For example, when working with Matroids, the following error may occur if the extension matroid-database is not present.
sage: ch = [M.characteristic_polynomial() for M in matroids.AllMatroids(5)]
---------------------------------------------------------------------------
FeatureNotPresentError Traceback (most recent call last)
....
To install matroid_database using the pip package manager, you can try to run:
!sage -pip install matroid-database
The hint on the last line shows how to add this database to your session. Instead of !sage -pip install matroid-database you can also type %pip install matroid-database (at the Sage prompt). The advantage of the latter option is that you do not have to restart the session.
Note that you cannot install all kinds of optional packages in S- and N- sessions. Specifically, this only works for the pip package manager. For all other installation instructions, you must work in a B- session.
Go back to the Table of Contents
The SageMath Docker Guide itself hardly takes up any space on your hard drive. The underlying Docker for Powershell takes up some more space (about 0.3 GB plus 1.7 GB for WSL). However, this is not the majority of the space that may be used. Most of it is due to the use of the software, namely downloading the SageMath software as described in section 2.3.
The most important thing to free up occupied space is therefore to remove these software versions from your computer. The size they take up on your device is indicated in the List of software that have been downloaded. To delete them, follow section 2.7. After that, do the following:
If you no longer want to use SageMath Docker Guide but want to keep Docker for Powershell, delete all downloaded SageMath software as described above. You can also delete the SageMath Docker Guide desktop icon if you want. That's all you need to do to free up used space.
If you don't like to use Docker for Powershell any more, open a Powershell terminal as described in section 1. To see the explicit name of the WSL distribution including the version number type
wsl -l -q
You can remove it by:
wsl --unregister DockerForPowershell-0.2
Replace the version number 0.2 by the one displayed in your terminal above.
If Docker for Powershell was the only WSL distribution you had on your system you may want to remove WSL, too. To do this open a Powershell terminal as before and type:
wsl --uninstall
Go back to the Table of Contents
If you want to use SageMath Docker Guide on Linux, you need to install Powershell on your system. To do so, follow the appropriate instructions on the Powershell installation page.
Next, start Powershell (for example, by typing pwsh in a bash terminal) and call Install-Module Microsoft.PowerShell.ConsoleGuiTools. You also need to set an alias for your terminal. For example, if you have a Mate terminal, set alias cmd=mate-terminal.
You also need to install Docker. If you don't have it, follow the instructions on the appropriate Docker installation page.
Instead of following the installation instructions for Windows as described in section 1, simply download the files sagemath_docker_guide.ps1 and proj_docker_guide.psm1 to the folder where you want to work with SageMath. After starting Powershell there, you can start the guide by executing .\sagemath_docker_guide.ps1.
The main difference from using it on Windows is the appearance of the selection windows. On Linux they look like the following example:
Here you have to select a line with the space key and then press Enter.
It would be great if this code made it easier for many Windows users to use SageMath. But of course there is still a lot of work to do to achieve this goal. In particular, this cannot be done by one person alone. Therefore, any help is very welcome. This can be suggestions or bug reports. Please use the issues of this repository. But pull requests that fix bugs, improve wording or implementation, or add more features, or even provide better screenshots (in english) are also welcome.