Wiki source code of Installing & configuring TLJH

Last modified by Jan Rhebergen on 2022/01/24 15:56
Hide last authors
Jan Rhebergen 1.1 1 This page describes the installation and configuration of "The Littlest Jupyter Hub" a.k.a. TLJH
2
3 Running TLJH inside a docker container is not supported, since it depends on systemd. Hence the alternative is to run a LXC ubuntu container and install TLJH inside of that container.
4
5 The approach is partially described here https://linuxcontainers.org/lxd/getting-started-cli/#ubuntu
6
7 = On the host (i.e. liszt) =
8
9 (% class="box" %)
10 {{{sudo apt install snapd
11 snap install lxd --channel=4.0/stable
12
13 lxc launch ubuntu:20.10 tljh
14 lxd init
15
16 lxc list
17 lxc start tljh
18 }}}
19
20 After the init command (above) follow the instructions here https://linuxcontainers.org/lxd/getting-started-cli/#initial-configuration and use sensible defaults. Once this new container runs we want to manipulate the setting such that it will always claim/set the same IP address for it's internal network interface. The reason for this is that we need to be able to set a fixed IP for the nginxproxymanager to use so the container can be reached from outside.
21
22 (% class="box" %)
23 {{{lxc config device override tljh eth0
24 lxc list --columns ns4
25 lxc config device set tljh eth0 ipv4.address 10.83.150.32
26 lxc restart tljh
27 }}}
28
29 The above mentioned IP address is obtained by simply inspecting the network interface inside the container using:
30
31 (% class="box" %)
32 {{{lxc shell tljh
33 ip add
34 }}}
35
36 The combination of docker iptables settings and deploying lxc is a little troublesome but can be fixed. If nothing is done this causes lxc not to have access to the outside (i.e. the internet). The two statements below should remedy the situation. The first (commented out) tries to be specific but did not work (further investigation needed). The second is more generic and because of that may not be judged safe enough. However in this case I think it is fine and acceptable.
37
38 (% class="box" %)
39 {{{#iptables -I DOCKER-USER -i lxdbr0 -o enp3s0 -j ACCEPT
40 iptables -I DOCKER-USER -j ACCEPT
41 }}}
42
43 = Inside TLJH shell =
44
45 After making sure the lxc container can be accessed over the internet and can also itself access internet we continue below to install tljh itself (**NB:** ##lxc shell tljh##).
46
47 (% class="box" %)
48 {{{sudo apt update; apt upgrade
49 sudo apt install python3 python3-dev git curl
50 curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin ganymede 
51 }}}
52
53 The name ganymede is chosen for the admin account as it is a moon of Jupiter the planet. Coincidentally it is not only the largest moon of Jupiter but the largest moon in our solar system and even bigger than the planet mercury although not as massive.
54
55 Applications need to know the IPs of hosts on the cluster. Hence as a precautionary measure we add them to the ##/etc/hosts## file like so:
56
57 (% class="box" %)
58 {{{root@tljh:~# cat /etc/hosts
59 127.0.0.1 localhost
60
61 # The following lines are desirable for IPv6 capable hosts
62 ::1 ip6-localhost ip6-loopback
63 fe00::0 ip6-localnet
64 ff00::0 ip6-mcastprefix
65 ff02::1 ip6-allnodes
66 ff02::2 ip6-allrouters
67 ff02::3 ip6-allhosts
68
69 #JBRv
70 192.168.166.130 liszt
71 192.168.166.222 beethoven
72 #JBR^
73 }}}
74
75 = Sharing data =
76
77 == solution one ==
78
79 Apart from sharing data using the ##nbgitpuller## extension we might also want to employ a local directory (% class="mark" %)(read only) (%%)with some material. This is realised as described below (**NB:** ##lxc shell tljh##):
80
81 (% class="box" %)
82 {{{mkdir -p /srv/data/shared_data
83 cd /etc/skel
84 ln -s /srv/data/shared_data shared_data
85 }}}
86
87 By putting this is the ##/etc/skel## it will be reproduced when new users are added (see https://tljh.jupyter.org/en/latest/howto/content/share-data.html)
88
89 == solution two ==
90
91 Another approach it is to use [[##nbgitpuller##>>https://github.com/jupyterhub/nbgitpuller#constructing-the-nbgitpuller-url]] as described [[here>>doc:UOG.Technical Documentation.Git & Gitea.WebHome]] in the section **//"using git with TLJH"//**.
92
93 == solution three ==
94
95 Here we employ [[##nextcloud##>>https://nextcloud.bladzij.de]] in combination with [[##rclone##>>https://rclone.org/]] as described here.
96
97 = Troubleshooting =
98
99 After an update (an reboot) it might occur that the container is not running. When executing ##lxc shell tljh## you might be shown this message:
100
101 (% class="box" %)
102 {{{snap-confine has elevated permissions and is not confined but should be. Refusing to continue to avoid permission escalation attacks}}}
103
104 This problem can be solved correctly (re)configuring ##apparmor## like below (as root):
105
106 (% class="box" %)
107 {{{apparmor_parser -r /etc/apparmor.d/*snap-confine*
108 apparmor_parser -r /var/lib/snapd/apparmor/profiles/snap-confine*
109
110 systemctl enable --now apparmor.service
111 systemctl start apparmor
112 }}}
113
114 Of course ##apparmor## need to be installed! (it should already be).