Installing Docksal

System requirements

Minimum RAM requirement: 4GB. 8GB or more recommended.

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 7 or newer

Installation

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

    curl -fsSL get.docksal.io | bash

  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

    curl -fsSL get.docksal.io | DOCKER_NATIVE=1 bash

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

    curl -fsSL get.docksal.io | bash

Linux. Other distributions

Compatibility

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.

Incompatible 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. Linux Shell installation options

Docksal on Windows requires Linux type shell to run. Choose the options you like.

  • Babun Recommended
    • Faster install, but CYGWIN is less native.
  • Ubuntu Application (WSL)
    • Beta. Harder to install, can ony use Docker for Mac, but native Linux shell, real Ubuntu on Windows.

Windows with Babun. Docker installation options

Using Babun as Linux type shell supports 2 options of Docker installation.

  • VirtualBox Recommended
    • Faster, somewhat less convenient to use and update.
  • Docker for Windows
    • Somewhat slower, excludes VirtualBox, but easier to use and update

Windows with Babun and VirtualBox

  1. Download and Install Babun

    Babun Site

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

    Open Babun and run:

    curl -fsSL get.docksal.io | bash

  3. Start the VM

    In Babun run:

    fin vm start

Windows with Babun and Docker for Windows

  1. Download and Install Babun

    Babun Site

  2. Download and Install Docker for Windows

    Docker for Windows

    Notes: computer will require logout and restart during the installation. See screen recording to know what to expect.

  3. Configure Docker for Windows

    Share your local drives with Docker for Windows:

    Sharing Windows drives with Docker

  4. Install Docksal

    Open Babun and run:

    curl -fsSL get.docksal.io | bash

Windows with Ubuntu App (WSL) and Docker for Windows

Warning: this way of using Docksal is not thoroughly tested. It has been proven to work, but quirks may happen.

Ubuntu application is previously known as Windows Subsystem for Linux (WSL)

  1. Install Ubuntu App

  2. Install and configure Docker for Windows

  3. Install Docksal

Updating Docksal

All Docksal components can be updated with a single command:

fin update

Uninstallation

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 uninstallation instructions for Ubuntu, Debian, Fedora, CentOS.