Project

General

Profile

Hacking prerequisites » History » Version 80

Brett Smith, 01/08/2025 04:35 PM
add configuration to the inventory to simplify running the playbook

1 1 Tom Clegg
{{>toc}}
2
3
h1. Hacking prerequisites
4
5
The Arvados test suite can run in a Docker container, a VM, or your workstation -- provided a few prerequisites are satisfied.
6
7
h2. Host options
8
9
h3. Starting on your workstation
10
11 70 Ward Vandewege
If your workstation is a debian buster system -- and you don't mind installing a bunch of packages on your workstation, some of them without apt -- the easiest way to get running is to run tests on bare metal. Skip to "Dependencies".
12 1 Tom Clegg
13
Other linux distributions should work too with some modifications, but it's probably easier to use a VM.
14
15
h3. Starting on a VM
16
17 71 Ward Vandewege
Another option is to create a virtual machine using something like Xen or VirtualBox, and run debian buster on it. The instructions below assume you have just a few basic requirements:
18 1 Tom Clegg
* SSH server
19
* sudo (@apt-get install sudo@)
20
* A user account with sudo privileges
21
22
h3. Starting in a docker container
23
24 55 Peter Amstutz
_[[Arvbox]] provides a preinstalled Docker-based dev environment.  The following instructions are for creating a dev environment inside Docker from scratch._
25
26 1 Tom Clegg
This can get you started quickly, but (unlike the above options) you'll need to remember to use something like @docker commit@ to save your state before shutting down your container.
27
28
See http://docker.io for more about installing docker. On debian it looks something like this.
29
30
<pre>
31 54 Tom Clegg
sudo apt-get install docker-ce
32 1 Tom Clegg
sudo adduser $USER docker
33
# {log out & log back in}
34
groups
35
# {should include "docker"}
36
</pre>
37
38 69 Ward Vandewege
Start up a new container with debian 10 (buster), make a new user and log in as that user:
39 1 Tom Clegg
40
<pre>
41 69 Ward Vandewege
docker run -it --privileged debian:10 bash
42 1 Tom Clegg
apt-get update
43 34 Tom Clegg
apt-get -y install sudo
44 1 Tom Clegg
adduser me
45 33 Tom Clegg
adduser me sudo
46 1 Tom Clegg
sudo -u me -i
47
</pre>
48 12 Joshua Randall
49 15 Tom Clegg
The &quot;--privileged&quot; is required in order for /dev/fuse to be accessible (without it, no tests that require FUSE will work).
50 1 Tom Clegg
51
h2. Install dev environment
52
53 78 Brett Smith
h3. With Ansible
54
55
This is a prototype still in development, but initial development was done in January 2025 and it can automate much of the process for you.
56
57
h4. Install Ansible
58
59
The simplest thing to do is @pip install@ Ansible inside a virtualenv:
60
61
<pre><code class="shell">sudo apt install python3-venv
62
python3 -m venv ~/arvados-ansible
63
~/arvados-ansible/bin/pip install "ansible~=8.7"
64
</code></pre>
65
66
If that works, you're done and you can go on to the next section. For background:
67
68
* The Arvados Ansible playbooks are tested with Ansible 8, which we use for its Python version compatibility. Older versions are known not to work. You're welcome to try newer versions if you want to for any reason, but they haven't been tested.
69
70
* There are "other installation options":https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html if you can't do this for some reason.
71
72
h4. Write an Arvados database configuration
73
74
Next, write an Arvados configuration file that defines how you want to set up the PostgreSQL database. Write a file @~/arvados-ansible/zzzzz.yml@ like this:
75
76
<pre><code class="yaml">Clusters:
77
  zzzzz:
78
    PostgreSQL:
79
      Connection:
80
        user: arvados
81
        password: GoodPasswordHere
82
        dbname: arvados_development
83
        host: localhost
84
        port: "5432"
85
</code></pre>
86
87 79 Brett Smith
The cluster ID must be @zzzzz@. You can change the @user@, @password@, and @dbname@ settings freely. Our Ansible playbook will configure PostgreSQL so your settings here work.
88
89
The playbook will always install the @postgresql@ server package. If you already have this installed and have configured it to listen somewhere other than the default, you may update @host@ and @port@ to reflect that. Note that @port@ is a string containing digits.
90
91 78 Brett Smith
h4. Write an Ansible inventory
92 1 Tom Clegg
93 80 Brett Smith
An inventory file tells Ansible what host(s) to manage, how to connect to them, and what settings they use. If you've installed Ansible on the same system where you want to install a test environment, write this inventory file to @~/arvados-ansible/inventory.ini@:
94 78 Brett Smith
95 1 Tom Clegg
<pre><code class="ini">[arvados-test]
96
localhost ansible_connection=local
97 80 Brett Smith
98
[arvados-test:vars]
99
# The path to the Arvados cluster configuration you wrote in the previous section.
100
arvados_config_file={{ lookup('env', 'HOME') }}/arvados-ansible/zzzzz.yml
101
102
# The primary user doing Arvados development and tests.
103
# This user will be added to the `docker` group.
104
# It defaults to the name of the user running `ansible-playbook`.
105
# If you want to configure a different user, set that here:
106
#arvados_dev_user=USERNAME
107 78 Brett Smith
</code></pre>
108
109
If that's sufficient, you can skip to the next section. If you want to do something fancier, like having Ansible install a test environment on one or more remote hosts, refer to the "Ansible inventory documentation":https://docs.ansible.com/ansible/latest/getting_started/get_started_inventory.html to learn how to write your own.
110 1 Tom Clegg
111 78 Brett Smith
h4. Run the playbook
112
113 1 Tom Clegg
The basic command to run the playbook is:
114 78 Brett Smith
115
<pre><code class="sh">cd arvados/tools/compute-images/ansible
116 80 Brett Smith
~/arvados-ansible/bin/ansible-playbook -i ~/arvados-ansible/inventory.ini -K install-test-env.yml</code></pre>
117 78 Brett Smith
118 80 Brett Smith
The playbook will install symlinks for Go, Node, Singularity, and Yarn under @/usr/local/bin@. The actual tools are installed under @/opt@. If you need different versions of these tools for other work, you'll need to customize your @PATH@ environment variable so the Arvados versions are found first when you're doing Arvados work.
119 78 Brett Smith
120
h3. Manually
121 76 Brett Smith
122
Start with Debian 10+ and run the following commands as root.
123 36 Tom Clegg
124 67 Tom Clegg
Note that the last command here ("arvados-server install -type test") installs additional debian packages to your system, along with additional software in /var/lib/arvados/ (such as suitable versions of Ruby and Go) that do not interfere with system packages. It also creates a postgresql database user named "arvados" with an insecure password. Don't expose this postgresql server to the internet or to untrusted users!
125 1 Tom Clegg
126 72 Ward Vandewege
<pre>
127 75 Tom Clegg
apt update
128
apt install wget ca-certificates
129
wget https://apt.arvados.org/bullseye/pool/main/a/arvados-server/arvados-server_2.4.3-1_amd64.deb
130
dpkg -i arvados-server_2.4.3-1_amd64.deb
131
arvados-server install -type test
132 74 Ward Vandewege
</pre>
133 73 Ward Vandewege
134 77 Tom Clegg
Alternatively, install Go &ge; 1.20 (see https://golang.org) and git, and run arvados-server from source.
135 73 Ward Vandewege
136 1 Tom Clegg
<pre>
137 77 Tom Clegg
wget -O- https://go.dev/dl/go1.22.1.linux-amd64.tar.gz | tar -C /usr/local -xzf -
138
ln -s /usr/local/go/bin/* /usr/local/bin/
139
140
apt install git build-essential libpam-dev
141
142 1 Tom Clegg
cd
143
git clone https://git.arvados.org/arvados.git
144 68 Ward Vandewege
cd arvados
145 67 Tom Clegg
go mod download
146 77 Tom Clegg
go run ./cmd/arvados-server install -type test
147 1 Tom Clegg
</pre>
148
149
h2. Start Postgres
150
151
_If you're running in a docker container_ you'll need to start Postgres manually:
152 9 Joshua Randall
153 47 Tom Clegg
<pre>
154 11 Joshua Randall
sudo /etc/init.d/postgresql start
155 60 Peter Amstutz
</pre>
156
157
(If you're on a regular workstation/server/VM, startup scripts have already taken care of that for you.)
158
159
h2. Setup groups
160
161
Make sure the fuse and docker groups exist (create them if necessary) and that the user who will run the tests is a member of them.
162 1 Tom Clegg
163
h2. Run tests
164
165
<pre>
166 67 Tom Clegg
time ~/arvados/build/run-tests.sh WORKSPACE=~/arvados
167 1 Tom Clegg
</pre>
168
169 14 Tom Clegg
During development, you'll probably want something more like this. It reuses the given temp directory, which avoids a lot of repetitive downloading of dependencies, and allows you to save time with @--skip-install@ or @--only-install sdk/ruby@ and so on.
170 1 Tom Clegg
171
<pre>
172 23 Tom Clegg
mkdir -p ~/.cache/arvados-build
173 67 Tom Clegg
time ~/arvados/build/run-tests.sh WORKSPACE=~/arvados --temp ~/.cache/arvados-build
174 1 Tom Clegg
</pre>