Add Codespaces as an alternative to install/use Annif (#27)

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "name": "Annif Tutorial Environment",
+  "build": {
+    "dockerfile": "../Dockerfile"
+  },
+  "customizations": {
+    "codespaces": {
+      // Avoid opening /README.md
+      "openFiles": []
+    },
+    "vscode": {
+      "settings": {
+          "terminal.integrated.defaultProfile.linux": "bash",
+          "terminal.integrated.profiles.linux": { "bash": { "path": "/bin/bash" } }
+      }
+    }
+  },
+  "features": {
+  },
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [5000]
+}

exercises/01_install_annif.md

@@ -3,11 +3,12 @@
 ## 1. Install Annif
 
 To be able to complete the exercises you need to install Annif on your own
-computer. There are three options to choose from:
+computer or GitHub Codespaces. There are four options to choose from:
 
 1. VirtualBox virtual machine image with preinstalled Annif
 2. Docker based install
 3. Local install using pip (Linux only)
+4. Install to GitHub Codespaces (_experimental_)
 
 ### 1.1. VirtualBox based install
 
@@ -107,14 +108,49 @@ exercises and the neural network (nn) feature for the NN ensemble exercises - se
 dependencies](https://github.com/NatLibFi/Annif/wiki/Optional-features-and-dependencies)
 in the Annif wiki for details.
 
+### 1.4. GitHub Codespaces install
+
+_This is experimental: all exercises have not been thoroughly tested._
+
+In this installation you will be using Annif in a GitHub hosted machine, which you will access via a terminal in your browser (in a VS Code editor remote session).
+For this you are required to have an account on GitHub.
+
+1. Open a page to configure a new codespace by clicking this badge:
+
+    [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/NatLibFi/Annif-tutorial/tree/codespaces)
+
+2. Select "4-core" for "Machine type" (the bottommost menu); other selections can be left to default values
+3. Click the green "Create codespace" button on bottom of the page 
+
+This will start a start a new codespace session: A screen with title "Setting up your codespace" and a terminal view will be shown indicating that a container is being build. 
+This takes about one minute.
+After this everything is set up: a panel for the terminal screen is on the right on browser window, on the bottom; you probably want to make that panel bigger by dragging from its edges.
+
+Now the codespace is running. Annif is already installed there and ready to be used for exercises!
+
+#### About using Codespaces
+- The same packages are installed in the codespace environment as in the Docker image, so you can use the nano editor, but files can be edited also with the VS Code editor: to create a new file, e.g. `projects.cfg`, right click on the empty of the opened Explorer panel (on left) , select "New File...", and a new panel opens for the file.
+- It is not necessary to stop an instance, [it happens automatically after 30 min timeout](https://docs.github.com/en/codespaces/getting-started/understanding-the-codespace-lifecycle#timeouts-for-github-codespaces), but to save your [free given CPU time](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts) it is good to [stop the codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace?tool=webui) when you are not using it:
+  - Go to [Your codespaces page](https://github.com/codespaces?repository_id=212338434) to see a list of all your codespaces of Annif-tutorial.  
+  - To the right of the codespace you want to stop, click the ellipsis (...).
+  - Click "Stop" codespace.
+- Stopped codespace can be restarted from the same page clicking its name on the list.
+  - If terminal panel does not open on restart, you can manually open one from the hamburger menu in top-left, select "Terminal" and "New Terminal".
+- _Just closing the browser tab does not stop the codespace._
+- [When stopping a codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace?tool=webui#about-stopping-and-starting-a-codespace) the data is persisted in it. Terminal window will be cleared.
+- Once you are finished with Annif-tutorial, and want to [delete your codespace](https://docs.github.com/en/codespaces/getting-started/understanding-the-codespace-lifecycle#deleting-a-codespace), go to [Your codespaces page](https://github.com/codespaces?repository_id=212338434), and click the ellipsis (...). Select "Delete".
+  - _Note that by default inactive codespaces are deleted after 30 days._
+
+
 ## 2. Verify that you can run Annif
 
 Once you have installed Annif and have opened a command line terminal
 window, check that Annif runs using the command:
 
     annif
 
-If you get a usage message, congratulations - you're up and running!
+If you get a usage message, congratulations - you're up and running and can now proceed with the exercises!
+Below are some additional practical hints.
 
 ### Shell completions
 You can also check that the tab-key completion works (in the case of local install the support for it first needs to be enabled, [see instructions](https://github.com/NatLibFi/Annif#shell-compeletions)).

exercises/03_web_ui.md

@@ -14,7 +14,7 @@ Annif will start up and keep running until you stop it (by pressing Ctrl-C).
 ## 2. Open the UI in the browser
 
 Use your browser to access the URL 
-[localhost:5000/](http://localhost:5000/) or [http://127.0.0.1:5000/](http://127.0.0.1:5000/).
+[localhost:5000/](http://localhost:5000/) or [http://127.0.0.1:5000/](http://127.0.0.1:5000/), or if using Codespace, click the green "Open in Browser" button in the opened window.
 
 You should see a simple user interface with a big empty text field.
 

exercises/README.md

@@ -89,6 +89,12 @@ Select your installation type. If you don’t know what to choose, we suggest us
 - [transcript of video](/transcripts/annif-install-linux.md)
 - [Annif README file with installation instructions](https://github.com/NatLibFi/Annif/blob/master/README.md)
 
+### 1.4. GitHub Codespaces install
+
+In this installation you will be using Annif in a GitHub hosted machine, which you will access via a terminal in your browser.
+
+- [exercise section](/exercises/01_install_annif.md#14-github-codespaces-install)
+
 ## :film_strip: Data sets
 This tutorial provides two example data sets; one of them should be chosen to be used in the exercises.