Home

🐳 alidock is a community-contributed tool that provides users with a consistent environment and precompiled builds.

⚠️ Even if you prefer not using alidock for some reason, alidock may be a "last resort" option when the installation does not work any longer on your main operating system. alidock provides users with the officially supported environment, therefore it will always work, whereas fixes for other operating systems are provided on a best-effort basis.

Support for alidock is done through opening an issue on its GitHub repository.

Install Docker

Docker has some extensive documentation covering the installation part.

🐧 Linux post-installation

By default, docker does not run as non-privileged user. You need to add your user to the docker group. Follow the instructions here: it should be sufficient to run:

sudo groupadd docker           # create docker group
sudo usermod -aG docker $USER  # add me to the docker group

You need to log out and log back in for the group settings to be effective.

🍏 macOS post-installation

On macOS, Docker runs in a lightweight virtual machine. There is some fine tuning to do once for all for making it work at a reasonable speed.

First off, you should make sure you are running at least macOS High Sierra, and your main disk's filesystem is APFS (not supported by earlier versions of macOS). Check your filesystem by opening the Disk Utility application. Your main disk (whose name is Macintosh HD by default) should report APFS as filesystem:

⚠️ Your disk should have been converted automatically to APFS during your High Sierra installation if possible. If this did not happen, you will still be able to use Docker, but it will be slower.

Start the Docker app now. A Docker icon will appear in the menu bar. Click on it, then click Preferences... on the menu, and select the Disk tab. Look at the Disk image location: the filename must end with .raw and not with .qcow2, as in the picture below:

If the extension is .qcow2, and your disk is APFS, you need to reset your Docker installation to factory settings by clicking the Reset bomb, and then the Reset to factory defaults button:

⚠️ You will lose your Docker volumes, if any, so beware. If you have a recent operating system with a solid state drive, and your installation of Docker is fresh, you probably don't need this step.

Docker runs in a lightweight virtual machine with not so many resources allocated to it by default. Click now the Advanced tab and you will see the following window:

Set the number of CPUs to the maximum allowed by your Mac, and at least 4 GiB of memory (8 GiB recommended). In some cases you may need even more RAM, especially at compile time, if you notice that your build jobs crash with errors like "internal compiler error" or "out of memory".

You need to press the Apply & Restart button to apply the settings.

Graphical applications in the container will require XQuartz installed on your Mac. Go to their website, download the most recent package, and install it.

⚠️ Logging out and back in again is required after the installation.

Test if it works by opening a terminal and typing xcalc. An ugly calculator should pop up.

Get alidock

alidock is available as a PyPI package. Get it with:

bash <(curl -fsSL https://raw.githubusercontent.com/alidock/alidock/master/alidock-installer.sh)

The installation will refuse to continue in case your Docker installation does not work. You will have to fix it first by following these steps. At the end of the installation you may be advised to open a new terminal in order to use it.

alidock self-updates automatically whenever a new stable release is out! 🎉

Use the alidock environment

Just type:

alidock

and you will have a shell inside your custom environment. This is how your prompt looks like when you are inside alidock:

[alidock] ~ $>

The first time you run it, a new container will be created. Subsequent runs will open new shells in the same container. You can run alidock as many times you want.

Your container's home directory is called /home/alidock and it is also visible from outside the container as ~/alidock. This means that your data will not be lost when you stop the container, and you will be able to use your favourite graphical editor from outside the alidock environment.

The container stays running in the background. If you don't need it any longer, you may want to stop it (as said, your data will not be lost):

alidock stop

Build software from within alidock

alidock comes with aliBuild preinstalled and configured. You do not need to install it. Furthermore, whenever alidock updates the base image, it will also get the newest aliBuild version, if any. The way you use aliBuild from within alidock is exactly the same as from outside.

Edit code with alidock

We have seen that alidock shares its home directory directory with your operating system. Your files are therefore visible from outside alidock under ~/alidock.

Since alidock may not come with all your editors, it is recommended you use your favorite editor or IDE on your operating system instead. Any modification done under ~/alidock is automatically visible inside the container.

If your editor has the option to trigger a build with a keystroke or custom command, remember that it will run the command from outside alidock. You can tell your editor to trigger a build inside alidock by using a custom command similar to (adapt it to your use case):

alidock exec aliBuild build AliPhysics --defaults next-root6 --debug

The trick lies in alidock exec.

Housekeeping

Docker and the container directory may get very large in size. From time to time, you may want to do some housekeeping.

Clean up old containers

Docker has a command to perform a cleanup of unused space. Run it from outside the container:

docker system prune -f

alidock will suggest you to run it whenever the container image is updated.

Clean up old builds

You may want to run, within an alidock session:

aliBuild clean --aggressive

to clean up temporary space.

Manual and thorough cleanup

aliBuild caches some stuff under ~/.sw from inside the container. You can cleanup your installation completely by running, from within an alidock session:

cd ~/.sw
shopt -s extglob  # enable shell negative matches
rm -rf !(MIRROR)  # remove all except MIRROR

~/.sw/MIRROR is the place where all the source code of all the packages is stored. You don't want to remove it, ever: if you keep it, you will save lots of time during subsequent builds.

Share MIRROR from your laptop

Do you have a previous aliBuild installation on your laptop? Do you want to migrate your current aliBuild installation? You already have the MIRROR directory somewhere on your laptop.

If you have followed the non-alidock instructions, this directory is called:

$ALIBUILD_WORK_DIR/MIRROR

From outside the container, do the following: first off, move your current MIRROR directory inside the container:

mkdir -p ~/alidock/.sw
rm -rf ~/alidock/.sw/MIRROR  # if it exists already, get rid of it and use the laptop's
mv $ALIBUILD_WORK_DIR/MIRROR ~/alidock/.sw/MIRROR

then link it to the old location:

ln -nfs ~/alidock/.sw/MIRROR $ALIBUILD_WORK_DIR/MIRROR

This will allow your laptop installation and your container installation to share the same mirror directory.

⚠️ Your laptop directory will link the container's directory. The opposite will not work.

macOS: exclude .sw from backup and indexing

Your .sw directory contains disposable data that already exists in remote repositories, plus it gets very big. alidock automatically excludes this directory from your Time Machine backups and Spotlight indexing.