docker

Installing using Docker

If any step seems confusing or doesn't work right away, check its sub items. Some are for clarification or error handling.

1. Recommended OS is Ubuntu focal. Any later Ubuntu LTS should work as well.
2. Shell commands in this tutorial assume you use bash as your shell.
3. Install:
   • git
   • Docker CE (Community Edition) → Docker Ubuntu Install Guide
   • an apache webserver with mod_proxy
     • optionally, some sort of user login mechanism for Apache.
     • How to configure your Apache
   • DevDock (a templating system for docker-compose).
     • Version 0.2.1 should work. At time of writing (2024-01-09), this is the latest.
4. Make sure that the hostname is configured correctly for use as a FQDN (fully-qualified domain name).
   • You can verify this by running hostname --fqdn – it should print a name that is registered in global DNS, or at least resolvable by all computers intended to access the anno server.
   • The FQDN should resolve to a public-facing IP address of the anno server.
   • … even when resolving locally (gethostip --decimal "$(hostname --fqdn)") or you may run into docker troubles when you try to use additional tools like our DOI bot. It's possible to make it work for local IP addresses, but we won't cover that here.
5. Open a shell session for user root.
6. Create an OS user as which the anno server shall run. In this tutorial, we'll assume
   • user name annosrv,
   • member of a group with the same name,
   • home directory is /srv/annosrv,
   • login disabled ⇒ the only way to get a shell as that user is sudo -su annosrv or similar.
     • Do not confuse sudo's -su flags with the su command, which would probably fail when login is disabled. With sudo, -s means to start a --shell, and -u annosrv means --other-user=annosrv.
7. chown --recursive annosrv:annosrv -- /srv/annosrv
8. Put the root shell aside, we'll need it again later.
9. Start a shell session as user annosrv.
10. … and cd to its home directory if you aren't there yet.
11. Ensure that user annosrv has no control over the docker daemon. (Earlier versions of this guide advised the opposite.)
    1. Test access to the docker daemon: Run docker version
    2. The expected good response should include the message "ERROR: Got permission denied while trying to connect to the Docker daemon socket".
    3. If that error message is missing, remove user annosrv from all docker-related OS user groups and reboot.
12. If you already have a /srv/annosrv/anno-server-22 from a previous install attempt, move it to some backup directory. The next step (cloning) would fail if the directory already exists.
13. git clone --single-branch --branch stable https://github.com/UB-Heidelberg/anno-server-22
14. Verify the cloning: ls anno-server-22/run_*.sh — the expected good response is anno-server-22/run_server.sh.

Intermezzo: DOI bot

If you want DOI registration for your annotations, this optional chapter shows how to install anno-doi-bot-23. The anno server works perfectly well even without a DOI bot.

1. If you do not need a DOI bot, jump to the next subchapter "Back to root".
2. Create a directory for the DOI bot modules. We'll assume /srv/annosrv/doibot.
3. cd /srv/annosrv/doibot
4. Clone the main DOI bot repo: git clone --single-branch --branch stable https://github.com/UB-Heidelberg/anno-doi-bot-23
5. If you also want the DataCite registry adapter: git clone --single-branch --branch stable https://github.com/UB-Heidelberg/anno-doi-bot-23-adapter-datacite
6. Pre-emptive hints for the next step:
   • You do not need to npm install those repos individually. Skip that step, because the docker install script will do that soon.
   • You already cloned them, so you can skip their cloning step.
   • Don't start the DOI bot or any adapter yet. DevDock will do that later.
7. With those hints in mind, set up each DOI bot component according to its readme (or similar docs), because it may have warnings or instructions not addressed above.

Back to root

1. Put the annosrv shell aside for later. Switch back to your root shell.
2. If you have chosen to do the DOI bot install part above, export an environment variable EXTRAS_DIR that points to where your DOI bot modules are. With the example paths, that would be: export EXTRAS_DIR=/srv/annosrv/doibot
3. In that root shell, run: /srv/annosrv/anno-server-22/util/install_dockerized.sh
   • It will create a temporary node.js docker container, mount the anno-server-22 directory into it, and use npm inside the container to arrange various things. (For details about what and why, see util/install_dockerized.md next to the script.)
   • If you have set an EXTRAS_DIR, the script will also install all Node.js modules that are subdirectories of EXTRAS_DIR.
4. You may now close the root shell. The further configuration should happen as user annosrv. (Or you can do them as anyone and later chown all files.)
5. One anno server installation can run several instances, each with their own docker-internal hostname. (The docker project will make its own virtual network with locally assigned hostnames, independent of DNS.) Choose a hostname for your first instance.
   • It should start with a letter and may consist of letters, numbers and hyphens. (No dots. This is not a FQDN.)
   • In this example, we will assume that hostname to be dkas22. ("dk" = Docker, "as22" = anno-server-22)
   • You will need this hostname again later.
6. Create an anno server instance config. That's a subdirectory in the anno-server-22 directory named cfg.@ + the instance's hostname.
   • An example config directory can be found in ../../cfg/ubhd-ex01/. To use it: cp -rnT -- docs/cfg/ubhd-ex01/ cfg.@dkas22
   • Directory naming explained: "cfg." = config, "@" = host-specific. In the future, there may be others like "cfg.site" and "cfg.vendor".
7. You can customize your instance config now or at any time later. See the example config's README.md for how. Most changes will take effect only when you restart the server.
   • ⚠ Make sure to review the ACL and security settings before you make your anno server accessible to users or the public.
8. Now you need to set up docker-compose. To make that easier, we use the templating system "DevDock".
   1. The next steps will require basic knowledge of DevDock, at least project/directory names and container control commands. You can find them in the DevDock Readme.
   2. A good place to put your DevDock project is inside your instance config directory.
   3. An example config directory can be found in ../../cfg/as22.devdock/. To use it: cp -rnt cfg.@dkas22/ -- docs/cfg/as22.devdock
9. The anno server software itself is now installed.

Next steps:

• Set up a reverse proxy and ensure some security aspects: see here.
• Prepare the database and start the server: See the README.md of the example DevDock project.