Installing Docksal

System requirements

RAM requirement: 8GB or more.

Mac

  • Must be a 2010 or newer model
  • macOS 10.11 or newer

Linux

  • CPU with SSE4.2 instruction set supported (most models released in the last 10 years)
  • Supported distributions: Debian with derivatives (Ubuntu, Mint, etc.), Fedora with derivatives (CentOS etc.)

If you get output from the following command, then your CPU is good to go:

cat /proc/cpuinfo | grep sse4_2

Linux distros outside of the Debian and Fedora family may still work (e.g., Alpine). You will have to install Docker manually, then install Docksal as usual on Linux.

Windows

  • CPU with hardware virtualization (VT-x/AMD-V) supported and enabled in BIOS.
  • Windows 10 or newer

Install Docksal

The installer script (get.docksal.io) requires administrative privileges to complete the installation. On all operating systems, fin cli tool is written to /usr/local/bin and Docksal’s IP address (192.168.64.100) is assigned to the host’s local network interface. On macOS, /etc/exports and /etc/resolver/docksal have to be modified, and nfsd service has to be restarted. On Linux, installer (re)installs the Docker service if needed. On Windows, there are additional requests for permissions to create network shares for local drives to share files with Docker and to mount them with the current user’s account and password.

Choose Operating System

Click your operating system to proceed to OS-tailored docs:

macOS Docker installation options

Click the preferred option to proceed to option-specific docs.

macOS with VirtualBox

With this method, Docker will run inside a VM in VirtualBox.

  1. Download and Install VirtualBox

    Download VirtualBox 5.2.20

  2. Enable Kernel extension (Why?)

    Go to System Preferences > Security & Privacy.
    If you do not see the Allow button it means the extension is already enabled.

    Allowing VirtualBox kernel extension

  3. Open Terminal app and run

    bash <(curl -fsSL https://get.docksal.io)

  4. Start the VM

    In Terminal app run:

    fin vm start

macOS with Docker for Mac

  1. Download and Install Docker for Mac

    Docker for Mac

  2. Start Docker for Mac

    Wait until it says “Docker is running” in the menubar icon menu.

  3. Open Terminal app and run

    DOCKER_NATIVE=1 bash <(curl -fsSL https://get.docksal.io)

Linux installation options

Click your repo to proceed to docs.

Linux. Debian, Ubuntu, Fedora

Debian with all derivatives (Ubuntu, Raspbian etc.), Ubuntu with derivatives (Mint, etc.), and Fedora with derivatives are supported out of the box with automatic installation.

  1. Check pre-requisites

    By default, Apache listens on 0.0.0.0:80 and 0.0.0.0:443. This will prevent Docksal reverse proxy from running properly. You can resolve it an any of the following ways:

    • Reconfigure Apache to listen on different host (e.g., 127.0.0.1:80 and 127.0.0.1:443)
    • Reconfigure Apache to listen on different ports (e.g., 8080 and 4433)
    • Stop and disable Apache

  2. Check your software.

    Check that you have installed and configured

    • curl
    • sudo

  3. Open Terminal and run

    bash <(curl -fsSL https://get.docksal.io)

Linux. Other distributions

If you cannot find your distribution in the list above, it does not mean it is not supported! Lesser known Debian, Ubuntu, or Fedora derivatives are most likely supported.

This happens because Docker on Linux is being installed using the official get.docker.com script. If your distribution is not in the list above, but get.docker.com supports it, then it is supported too and you can follow the steps for compatible distributions.

In case your distribution in not compatible with get.docker.com, you will need to install latest stable Docker for your distribution first, and then follow the steps for compatible distributions.

Windows Docker installation options

Click the preferred option to proceed to option-specific docs.

  • VirtualBox Recommended
    • Use if your other VMs are in VirtualBox/Vagrant.
  • Docker for Windows
    • Can be faster, but not compatible with VirtualBox (don’t use if you have existing VMs in VirtualBox/Vagrant)

Windows and VirtualBox

  1. Enable Windows Subsystem for Linux (WSL) support

    WSL

  2. Install Ubuntu 18.04 app from Microsoft Store

    WSL

  3. Install Docksal (VirtualBox will be installed automatically if necessary)

    Open WSL and run:

    bash <(curl -fsSL https://get.docksal.io)

  4. Start Docksal

    In WSL run:

    fin system start

Windows and Docker for Windows

  1. Enable Windows Subsystem for Linux (WSL) support

    WSL

  2. Install Ubuntu 18.04 app from Microsoft Store

    WSL

  3. Download and Install Docker for Windows

    Docker for Windows

  4. Configure Docker for Windows

    Share your local drives with Docker for Windows:

    Sharing Windows drives with Docker

  5. Install Docksal

    Open WSL and run:

    DOCKER_NATIVE=1 bash <(curl -fsSL https://get.docksal.io)

Update Docksal

All Docksal components can be updated with a single command:

fin update

Uninstall Docksal

If you used VirtualBox

The steps below will remove the Docksal VM and cleanup all Docksal stuff.

fin system stop
fin vm remove
rm -rf "$HOME/.docksal"
rm -f /usr/local/bin/fin

Optionally, remove VirtualBox application.

If you used Docker for Mac / Docker for Windows

The steps below will remove Docksal project containers (files untouched) and stop Docksal system services.

fin cleanup
fin system stop
rm -rf "$HOME/.docksal"
rm -f /usr/local/bin/fin

Optionally, remove Docker for Mac / Docker for Windows application.

If you used Linux

The steps below will remove Docksal project containers (files untouched) and stop Docksal system services.

fin cleanup
fin system stop
rm -rf "$HOME/.docksal"
rm -f /usr/local/bin/fin

Optionally, follow Docker removal instructions for Ubuntu, Debian, Fedora, CentOS.