Skip to content

Installation

To install it localy, you first need to clone this repository to your local machine, or the machine that you want the Alyx server to run on.

It is ideal that you use git for the cloning / updating of your database.

Download

Clone this repository into your computer :

  • by using your command line interface, navigate to the folder where you want your installation files to sit (anywhere in your Documents folder is a location that would make sense). Usually using the cd Myfolder/mysubfolder command.

  • do git clone https://github.com/JostTim/haiss-alyx.git

  • swtich to the docker branch by doing git fetch --all (to fetch all changes to the docker branch and all the others branches) then git checkout docker (to sitch to the docker branch that you now have the info about)

Configuration

Configure your installation :

  • by using pdm, a package manager that will make things much easier. Please see how to install pdm if you don't have it already.
  • Ensure your terminal's current directory is again in the folder where you cloned the repository, previously (by using cd)
  • Ensure you have python 3.12 installed. If you are onwindows, and easy way is to go on the Windows Store and just type python 3.10, then install it.
  • do pdm install. Pdm should start installing the necessary packages locally, and should select the python version that is appropriate for this install. If not, please manually select the proper one using pdm use.
  • Now, you should have the utility scripts designed to ease Alyx configuration, de ployment and maintenance available. You can check them by doing pdm run --list
  • Start the configure script by running pdm run configure
  • This script shall walk you through the configuration process, and generate the necessary config files in the config folder of the repository you cloned from github. You can edit those as will afterwards, if you require additionnal changes. This repository is not managed via git, so you can add / remove / change things in this repository without worrying about pulling changes from the source github repository to get updates, at a later time, and your files are not stored online (as they may contain sensitive passwords, etc.)

First launch

Deploy locally on Docker

  • You will need Docker Desktop for this part, please ensure you downloaded it and that the virtualization engine works for your machine (disable/install/troubleshoot WSL2 if it does not work, for some users on windows 10). Please also note that installing docker desktop might require you to have the latest updates on your operating system, so please ensure you did these updates.
  • Again, ensure your terminal's current directory is again in the folder where you cloned the repository, previously (by using cd)
  • using previously installed pdm you will be able tu run the utility scripts that wrap around docker commands, to install and orchestration of containers decribed througout the docker's compose.yml file, and the docker folder. See in the section containers below for explanation of the roles of each containter service used here.
  • Start by doing pdm run fresh-build.
  • This will start by pulling the linux images necessary for the containers to run, and then instanciate them correctly as decribed in the docker compose and docker files.

  • If everything runs correctly, you should end up with a message similar to :

    log django_server | Starting Gunicorn to serve django alyx... django_server | [2024-12-09 13:13:38 +0000] [309] [INFO] Starting gunicorn 23.0.0 django_server | [2024-12-09 13:13:38 +0000] [309] [INFO] Listening at: http://0.0.0.0:8000 (309) django_server | [2024-12-09 13:13:38 +0000] [309] [INFO] Using worker: sync django_server | [2024-12-09 13:13:38 +0000] [310] [INFO] Booting worker with pid: 310 (the number here is not important and may be different when you run this)

Possible errors : - If you get an error similar to : log error during connect : Get .... open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified. It means that the docker desktop service is not launched. Please make sure the docker desktop application you installed previously is running.

Turn off, restart and maintain

  • To turn off the containers, you can run anytime from a terminal the command pdm run stop, wile the current working directory of your terminal is at the root of the repository you cloned from github.
  • To start it again, you can run pdm run start. Please note that this will not work if you didn't had a successfull build previously of if you deleted previously built-containers or volumes. (see online for info about what is a docker volume)

  • To re-build it after changes, but not deleting current data saved through volumes, you can run pdm run build. This can cause unpredictible results as you need to know what you do, so this command is particulary usefull for developement, but for a simple useage, working with backup files and using the pdm run fresh-build command is advised instead.

  • Mainteance can be performed using the commands pdm run interact and pdm run manage. Again these are most usefull for developement and should not be necessary for simple use.