deprecated Computer Setup
In general, you will need to have the ability to install software! We know that this is becomingly increasingly rare due to security restrictions.
Our strategy for dealing with this is to encourage cogent3 users and developers to use isolated containers for their work. This means that you can install whatever you want in your container, and it will not affect your host machine. We will be using Docker for this workshop. You may still require help from your IT department to install the docker host on your machine, but once that is done, you will be able to install whatever you want in your container.
Docker is a container technology that is available for all major operating systems. It is essentially a light weight version of linux isolated from your host OS. We provide a docker configuration file that will build a container with all the software you need for the workshop.
graph LR
subgraph t["`Configuration`"]
a[install docker host]
b[create DockerFile]
c["`docker *build* -f DockerFile .`"]
end
subgraph u["`Use`"]
d["`docker *run* image`"]
e[browse container remotely]
f[Edit code inside container]
g["`docker *stop*`"]
h(("docker --rm
(remove)"))
i[(loads workspace from the host OS)]
j[(writes workspace to the host OS)]
end
a-->b-->c
t---->u
i-->e
i-->f
e-->j
f-->j
d-->i
j-->g
g-->h
Get your IT department to install Docker Desktop and VS Code.
Installing Docker and VS Code on Windows
- Windows 10 64-bit: Pro, Enterprise, or Education (Build 16299 or later). Hyper-V and Containers Windows features must be enabled for Docker Desktop.
- Windows 11: Docker Desktop now supports Windows 11.
- WSL 2 backend: Recommended for Docker on Windows. Requires Windows 10 Version 1903 or higher with Build 18362 or higher.
- Windows: Windows 7 (with .NET Framework 4.5.2), 8/8.1, or 10.
-
Enable Hyper-V: Before installing Docker Desktop, ensure Hyper-V is enabled. Use PowerShell as an Administrator and run the following command:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All -
Download Docker Desktop: Visit the Docker Desktop for Windows download page.
-
Install Docker Desktop: Follow the on-screen instructions in the installer. Docker will start automatically after installation. This will require Administrator privileges.
-
Switch to WSL 2 (recommended): Docker Desktop defaults to Hyper-V. To use the WSL 2 backend, ensure WSL 2 is set up. Then, in Docker settings under "General", enable "Use the WSL 2 based engine".
-
Download VS Code: Visit the VS Code download page.
-
Install VS Code: Follow the on-screen instructions in the installer.
-
Install Essential Extensions: Once installed, consider adding the following VS Code extensions:
Note: If you're using an older version of Windows or Windows 10 Home, you might need to use "Docker Toolbox" instead of Docker Desktop. However, Docker Desktop is the recommended version for newer systems, as it provides a more integrated and user-friendly experience.
Installing Docker and VS Code on Linux
- A 64-bit version of one of these Linux distributions:
- Ubuntu (Bionic 18.04 or newer)
- Debian (Stretch or newer)
- CentOS (7 or newer)
- Fedora (30 or newer)
- Most modern Linux distributions are supported.
-
Update your package manager:
sudo apt-get update -
Install required packages:
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common -
Add Docker's GPG key:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - -
Add Docker's APT repository:
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" -
Update your package manager again:
sudo apt-get update -
Install Docker:
sudo apt-get install docker-ce -
Start Docker and enable it to start on boot:
sudo systemctl start dockersudo systemctl enable docker
Note: On Linux, the Docker daemon binds to a Unix socket instead of a TCP port. By default, that Unix socket is owned by the user root and other users can access it with sudo. For a non-root user to run Docker commands without sudo, the user must be added to the docker group.
To add a user to the docker group:
sudo usermod -aG docker <username>-
Update your package manager:
sudo apt update -
Install required packages:
sudo apt install software-properties-common apt-transport-https wget -
Import Microsoft's GPG key:
wget -q https://packages.microsoft.com/keys/microsoft.asc -O- | sudo apt-key add - -
Enable the Visual Studio Code repository:
sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main" -
Install Visual Studio Code:
sudo apt update
sudo apt install code
-
Install Essential Extensions: Once installed, consider adding the following VS Code extensions:
Note: The above instructions are tailored for Ubuntu-based distributions. If you're using a different Linux distribution, you might need to adjust package manager commands accordingly (e.g.,
yumfor CentOS ordnffor Fedora).
Installing Docker and VS Code on macOS
- Mac hardware must be a 2010 or newer model.
- macOS must be version 10.14 or newer.
- VirtualBox prior to version 4.3.30 must not be installed.
- macOS 10.10 or newer.
Note: The following instructions are for installing Docker Desktop on macOS. MacOS users also have the option of using colima, which is a lighter weight container host that does not require a hypervisor. If you'd prefer to use Colima instead, see the Colima installation instructions.
-
Download Docker Desktop for Mac: Navigate to Docker Desktop for Mac and click on "Get Docker".
-
Install Docker:
- Open the downloaded
.dmgfile. - Drag and drop the Docker.app into the Applications folder. This may require Administrator privileges.
- Double-click Docker.app to start Docker.
- Open the downloaded
-
Verify Installation:
- Click on the Docker icon in the top right menu bar.
- Select "About Docker" to check that you have the latest version.
-
Download Visual Studio Code for Mac: Navigate to VS Code for Mac and click on "Download for Mac".
-
Install Visual Studio Code:
- Open the downloaded
.zipfile. - Drag and drop the Visual Studio Code.app into the Applications folder.
- Open the downloaded
-
Open Visual Studio Code:
- Navigate to your Applications folder and open Visual Studio Code.
- Optionally, drag the app icon to your dock for easier access in the future.
-
Install Essential Extensions: Once installed, consider adding the following VS Code extensions:
Note: Ensure you have the necessary permissions to install applications on your Mac. If prompted, enter your macOS user password to allow installations.
The following screen cast is on how to build a docker image for cogent3 on your machine, run it, and check your setup is correct, and you are ready for the workshop.
setup_machine.mp4
To begin ensure the docker daemon is running on your host OS.
docker info should return information about your docker installation.
Clone the cogent3workshop repository to your local machine, and make sure that the cogent3workshop/docker subdirectory contains the DockerFile configuration file.
This container downloads and installs the following dependencies:
- Python3 (latest shipping version)
- Cogent3 (latest shipping version)
- ZSH (a more descriptive linux shell)
- OhMyZSH (a framework for managing ZSH configuration)
The container also makes a directory `/workspace`` for all files that you will be working on (that will persist between container sessions) and starts a jupyter server in that directory.
Note the container also sets up a virtual environment c3workshop that will give you an isolated python environment, and the .vscode directory contains settings.json to ensure that VS code uses only virtual environments to interpret jupyter notebooks.
To build the Docker image, navigate to the root of the repository and run the following command to build a docker image named cogent3workshop using the Dockerfile in the docker directory:
docker build --tag cogent3workshop -f docker\DockerFile .It should take around 90s to build the image. You can check that the image was built successfully by running the following command:
docker images cogent3workshopTo start a Docker container using the image you just built, run the following command in a linux terminal (eg: from the terminal in VS Code):
docker run -it --rm -p 8888:8888 -v ${PWD}:/workspace cogent3workshopYou can also run this natively in your OS if you use an absolute path for the workspace directory. For example, on Windows, you could use the following command:
docker run -it --rm -p 8888:8888 -v C:\Users\username\Documents\cogent3workshop\:/workspace cogent3workshopon a Mac, you could use the following command:
docker run -it --rm -p 8888:8888 -v /Users/username/Documents/cogent3workshop/:/workspace cogent3workshopThis command does the following:
-
run: Runs a jupyter server in a new container -
-it: Allocates an interactive terminal. If you stop the jupyter server with ctrl-c, the container will exit. -
--rm: Automatically removes the container when it exits. -
-p 8888:8888: Maps port 8888 on the host to port 8888 in the container to allow access to the jupyter server from your host OS. -
-v ${PWD}docker\workspace\:/workspace: Mounts the root of your current directory on the host to/workspacein the container -
cogent3workshop: The name of the image we just built
You can connect to the jupyter server from your host OS by browsing to localhost:8888. You will need to enter the token displayed in the terminal when you started the container.
It will be in a line that looks like this
http://127.0.0.1:8888/tree?token=c9f817e64deb48b776ae74e6df6caede88a1a6e714448a23
Copy the token, then paste it into the jupyter server login page, and click Log in.
You can create a test notebook in the container by clicking the New button in the top right corner of the jupyter server page and selecting Python 3. This will create a new notebook in the /workspace directory in the container. You can then test that you can connect to cogent3 and quesy it's version using the commands below:
import cogent3
cogent3.__version__
To stop the container, press ctrl-c in the terminal where you started the container. If you no longer have the terminal open, you can stop the container using the following commands:
Find the container ID using the following command:
docker ps -allThis will list all running/stopped containers. Find the container ID for the container you want to stop.
Then, run the following command to stop the container:
docker stop <container_id>To restart the container if you have stopped it, run the following command:
docker start <container_id>-
Click the button in the bottom left corner of the VS Code window that says
><and selectRemote-Containers: Attach to Running Container...
-
Select the container you want to attach to from the list of running containers.
-
VS Code will open a new window with the container attached. You can now edit files in the container using VS Code.
- In the attached VS Code instance, you can either create a new Jupyter notebook by right-clicking in the Explorer, selecting New File, and giving it a .ipynb extension, or you can open an existing .ipynb file from the /workspace directory
- Note: your default directory will be the /workspace directory in the container, which will be mounted to the current director (when you ran the docker run command) in your host OS. Any files you create in the container will persist between container sessions.
- The Jupyter extension in VS Code provides an interactive interface similar to the classic Jupyter web interface. You can add cells, run code, visualize outputs, and more.
ZSH is a more descriptive shell for working with the terminal. To use it in VS Code, open a terminal in VS Code using the command ctrl-and then typezsh` and press enter. You can then use the terminal as you normally would.
You can also choose a new ZSH shell in the terminal drop down.
You can also tell VS Code that you want to default to ZSH shells when you open a new terminal by clicking on the preferences cog icon, selecting settings and modifying the Terminal > Integrated > Default Profile: Linux setting to zsh.
By default containers are given random names, like condescending_tesla. To explicitly name a container, add the following argument to the docker run command:
--name <container_name>when referring to a container using docker command, you can use either the container ID or the container name.
To run a file in the container, add the command and it's arguments to the end of the docker run command:
docker run <command> <arguments>eg: To run a python script you created in your workspace directory in the container and then exit the container:
docker run --rm cogent3workshop python -m example.pyto run the container as an immediate terminal session that uses zsh as a shell and removes the container once the session is exited:
docker run -it --rm cogent3workshop /usr/bin/zshNote: each of these will prevent the default run command of the container (starting a jupyter server) from running.
Once inside the Docker container, you will be in the /workspace directory containing all the files that are in the directory in your host OS you were currently in when you ran the docker run command. You can use the cd command to navigate to other directories in the container. Note the workspace directory is mounted to your host OS's directory so any files you create there in the container will persist between container sessions.
To remove the Docker image you created, first find the image ID using:
docker imagesThen, remove the image using:
docker rmi <image_id>Replace <IMAGE_ID> with the ID of the image you want to remove.