Install Docksal

System requirements

RAM requirement: 8GB or more.

Mac

Must be a 2010 or newer model.

Linux

CPU with SSE4.2 instruction set supported (most CPUs). If you get output from the following command, then your CPU is good to go:

cat /proc/cpuinfo | grep sse4_2

If the output is empty, see the troubleshooting docs for a workaround.

Windows

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

Install Docksal

Administrative Privileges

The installer script (get.docksal.io) requires administrative privileges to complete the installation.

Here’s why:

  • All systems: fin cli tool is written to /usr/local/bin (all systems)
  • All systems: 192.168.64.100 (Docksal’s canonical IP) is assigned to the host’s local network interface (all systems)
  • macOS: /etc/exports and /etc/resolver/docksal have to be modified, nfsd service has to be restarted
  • Linux: install/update the Docker service if necessary
  • 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.

What is your operating system?

Click to jump to OS-tailored docs:

macOS installation options

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

macOS with VirtualBox

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

  1. Open Terminal app and run

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

VirtualBox will be installed automatically if necessary. Follow the prompts in the Terminal app.

macOS with Docker Desktop

Starting with Docker Desktop v2.2.0.0+, the eTDL (base domain) for Docksal projects had to be changed from docksal to docksal.site. If this change has adverse effects for your project(s), you can downgrade Docker Desktop to v2.1.0.5 as a temporary measure.

  1. Install Docker Desktop for Mac v4.29.0

    Docker Desktop for Mac v4.29.0 (Intel chip) Docker Desktop for Mac v4.29.0 (Apple silicon)

  2. Start Docker Desktop

    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, and Fedora distributions

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.

Docksal uses the official get.docker.com script to automate the setup of Docker on Linux. 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.

If your Linux distribution is not compatible with get.docker.com, you will first need to install the latest stable Docker version for your distribution manually, complete the post-install instructions to be able to manage Docker as a non-root user, and then follow the steps for compatible distributions.

Windows installation options

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

  • VirtualBox Recommended
    • Faster, allows launching Vagrant alongside.
  • Docker Desktop
    • Easier to use. Do not use if you have existing Vagrant projects or VirtualBox VMs

Windows and VirtualBox

  1. Enable Windows Subsystem for Linux (WSL 1) support

    Enabling WSL

    Note: Do NOT install or upgrade to WSL 2. It is not yet supported in Docksal (see #1055).

  2. Install Ubuntu 20.04 app from Microsoft Store

    Ubuntu App for Windows

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

    Open Ubuntu shell and run:

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

Windows and Docker Desktop

Starting with Docker Desktop v2.2.0.0+, the eTDL (base domain) for Docksal projects had to be changed from docksal to docksal.site. If this change has adverse effects for your project(s), you can downgrade Docker Desktop to v2.1.0.5 as a temporary measure.

  1. Enable Windows Subsystem for Linux (WSL 1) support

    Enabling WSL

    Note: Do NOT install or upgrade to WSL 2. It is not yet supported in Docksal (see #1055).

  2. Install Ubuntu 20.04 app from Microsoft Store

    Ubuntu App for Windows

  3. Install Docker Desktop for Windows v4.29.0

    Docker Desktop for Windows v4.29.0

  4. Configure Docker Desktop on Windows

    4.1. Share your local drives with Docker for Windows:

    Share your Windows drives with Docker Desktop

    4.2. Share Docker Desktop port to the local network:

    Expose Docker daemon on tcp://localhost:2375 without TLS

  5. Install Docksal

    Open Ubuntu shell 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 Desktop

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, uninstall Docker Desktop.

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.