github.com/drud/ddev@v1.21.5-alpha1.0.20230226034409-94fcc4b94453/docs/content/users/install/ddev-installation.md (about)

     1  # DDEV Installation
     2  
     3  Once you’ve [installed a Docker provider](docker-installation.md), you’re ready to install DDEV!
     4  
     5  Installing and upgrading DDEV are nearly the same thing, because you're upgrading the `ddev` binary that talks with Docker. You can update this file like other software on your system, whether it’s with a package manager or traditional installer.
     6  
     7  === "macOS"
     8  
     9      ## macOS
    10  
    11      ### Homebrew
    12  
    13      [Homebrew](https://brew.sh/) is the easiest way to install and upgrade DDEV:
    14  
    15      ```bash
    16      brew install drud/ddev/ddev
    17      ```
    18  
    19      ```bash
    20      brew upgrade ddev
    21      ```
    22  
    23      As a one-time initialization, run
    24  
    25      ```bash
    26      mkcert -install
    27      ```
    28  
    29      ### Install Script
    30  
    31      !!!tip
    32          The install script works on macOS, Linux, and Windows WSL2.
    33  
    34  
    35      Run the [install script](https://github.com/drud/ddev/blob/master/scripts/install_ddev.sh) to install or update DDEV. It downloads, verifies, and sets up the `ddev` binary:
    36  
    37      ```
    38      curl -fsSL https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh | bash
    39      ```
    40  
    41      You can include a `-s <version>` argument to install a specific release or a prerelease version:
    42  
    43      ```
    44      curl -fsSL https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh | bash -s v1.19.5
    45      ```
    46  
    47  === "Linux"
    48  
    49      ## Linux
    50  
    51      ### Debian/Ubuntu
    52  
    53      DDEV’s Debian and RPM packages work with `apt` and `yum` repositories and most variants that use them, including Windows WSL2:
    54  
    55      ```bash
    56      curl -fsSL https://apt.fury.io/drud/gpg.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/ddev.gpg > /dev/null
    57      echo "deb [signed-by=/etc/apt/trusted.gpg.d/ddev.gpg] https://apt.fury.io/drud/ * *" | sudo tee /etc/apt/sources.list.d/ddev.list
    58      sudo apt update && sudo apt install -y ddev
    59      ```
    60  
    61      Update with your usual commands:
    62  
    63      ```bash
    64      sudo apt update && sudo apt upgrade
    65      ```
    66      
    67      !!!tip "Removing Previous Install Methods"
    68          If you previously used DDEV’s [install script](#install-script), you can remove that version:
    69  
    70          ```
    71          sudo rm -f /usr/local/bin/ddev /usr/local/bin/mkcert /usr/local/bin/*ddev_nfs_setup.sh
    72          ```
    73      
    74          If you previously [installed DDEV with Homebrew](#homebrew), you can run `brew unlink ddev` to get rid of the Homebrew version.
    75  
    76      ### Fedora, Red Hat, etc.
    77  
    78      ```bash
    79      echo '[ddev]
    80      name=DDEV Repo
    81      baseurl=https://yum.fury.io/drud/
    82      enabled=1
    83      gpgcheck=0' | sudo tee -a /etc/yum.repos.d/ddev.repo
    84  
    85      sudo dnf install --refresh ddev
    86      ```
    87  
    88      In the future you can update as usual using `sudo dnf upgrade ddev`. (Signed repository support will be added in the near future.)
    89  
    90      ### Arch Linux
    91  
    92      For Arch-based systems including Arch Linux, EndeavourOS and Manjaro, we maintain the [ddev-bin](https://aur.archlinux.org/packages/ddev-bin/) package in AUR. To install, use `yay -S ddev-bin` or whatever other AUR tool you use; to upgrade `yay -Syu ddev-bin`.
    93  
    94      As a one-time initialization, run `mkcert -install`.
    95  
    96      ### Alternate Linux Install Methods
    97  
    98      You can also use two macOS install methods to install or update DDEV on Linux: [Homebrew](#homebrew) (only on AMD64 computers) and the standalone [install script](#install-script).
    99  
   100  === "Windows"
   101  
   102      ## Windows
   103  
   104      You can install DDEV on Windows three ways:
   105  
   106      1. [Using WSL2 with Docker inside](#wsl2-docker-ce-inside-install-script)
   107      2. [Using WSL2 with Docker Desktop](#wsl2-docker-desktop-install-script)
   108      3. [Installing directly on traditional Windows](#traditional-windows) with an installer
   109  
   110      **We strongly recommend using WSL2.** While its Linux experience may be new for some Windows users, it’s worth the performance benefit and common experience of working with Ubuntu and Bash.
   111  
   112  
   113      ### Important Considerations for WSL2 and DDEV
   114  
   115      * WSL2 is supported on Windows 10 and 11.  
   116        All Windows 10/11 editions, including Windows 10 Home support WSL2.
   117      * WSL2 offers a faster, smoother experience.  
   118        It’s vastly more performant, and you’re less likely to have obscure Windows problems.
   119      * Projects should live in the Linux filesystem.  
   120        WSL2’s Linux filesystem (e.g. `/home/<your_username>`) is much faster, so keep your projects there and **not** in the slower Windows filesystem (`/mnt/c`).
   121      * Custom hostnames are managed via the Windows hosts file, not within WSL2.  
   122        DDEV attempts to manage custom hostnames via the Windows-side hosts file—usually at `C:\Windows\system32\drivers\etc\hosts`—and it can only do this if it’s installed on the Windows side. (DDEV inside WSL2 uses `ddev.exe` on the Windows side as a proxy to update the Windows hosts file.) If `ddev.exe --version` shows the same version as `ddev --version` you’re all set up. Otherwise, install DDEV on Windows using `choco upgrade -y ddev` or by downloading and running the Windows installer. (The WSL2 scripts below install DDEV on the Windows side, taking care of that for you.) If you frequently run into Windows UAC Escalation, you can calm it down by running `gsudo.exe cache on` and `gsudo.exe config CacheMode auto`, see [gsudo docs](https://github.com/gerardog/gsudo#credentials-cache).
   123      * WSL2 is not the same as Docker Desktop’s WSL2 engine.  
   124        Using WSL2 to install and run DDEV is not the same as using Docker Desktop’s WSL2 engine, which itself runs in WSL2, but can serve applications running in both traditional Windows and inside WSL2.
   125  
   126      The WSL2 install process involves:
   127  
   128      * Installing Chocolatey package manager (optional).
   129      * One time initialization of mkcert.
   130      * Installing WSL2 and installing a distro like Ubuntu.
   131      * Optionally installing Docker Desktop for Windows and enabling WSL2 integration with the distro (if you're using the Docker Desktop approach).
   132      * Installing DDEV inside your distro; this is normally done by running one of the two scripts below, but can be done manually step-by-step as well.
   133  
   134      ### WSL2 + Docker CE Inside Install Script
   135  
   136      This scripted installation prepares your default WSL2 Ubuntu distro and has no dependency on Docker Desktop. It is designed to be able to run multiple times without breaking anything.
   137  
   138      The provided PowerShell script can do most of the work for you, or you can handle these things manually. (This script works with the built-in PowerShell v5, but not with the newer v7.)
   139  
   140      In all cases:
   141      
   142      1. Install WSL2 with an Ubuntu distro.
   143  
   144          * Install WSL with
   145              ```
   146              wsl --install
   147              ```
   148  
   149          * Reboot if required. (Usually required.)
   150  
   151          * Visit the Microsoft Store and install the *updated* ["Windows Subsystem for Linux"](https://apps.microsoft.com/store/detail/windows-subsystem-for-linux/9P9TQF7MRM4R) and click "Open". It will likely prompt you for a username and password for the Ubuntu WSL2 instance it creates.
   152  
   153          * Verify that you now have an Ubuntu distro set as default by running `wsl.exe -l -v` 
   154  
   155          If you already have WSL2 but don't have an Ubuntu distro, install one by running `wsl.exe --install Ubuntu`. 
   156  
   157          If that doesn't work for you, see the [manual installation](https://docs.microsoft.com/en-us/windows/wsl/install-manual) and linked [troubleshooting](https://docs.microsoft.com/en-us/windows/wsl/troubleshooting#installation-issues).
   158  
   159      2. In an administrative PowerShell (5) run [this PowerShell script](https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev_wsl2_docker_inside.ps1) by executing: 
   160  
   161          ```powershell
   162          Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; 
   163          iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev_wsl2_docker_inside.ps1'))
   164          ```
   165      3. In *Windows Update Settings* → *Advanced Options* enable *Receive updates for other Microsoft products*. You may want to occasionally run `wsl.exe --update` as well.
   166  
   167      Now you can use the "Ubuntu" terminal app or Windows Terminal to access your Ubuntu distro, which has DDEV and Docker working inside it.
   168  
   169      ### WSL2 + Docker Desktop Install Script
   170  
   171      This scripted installation prepares your default WSL2 Ubuntu distro for use with Docker Desktop. It is designed to be able to run multiple times without breaking anything.
   172  
   173      You can do these things manually, or you can do most of it with the provided PowerShell (5) script. 
   174      In all cases:
   175      
   176      1. Install WSL2 with an Ubuntu distro. On a system without WSL2, just run:
   177          ```powershell
   178          wsl --install
   179          ```
   180  
   181          Verify that you have an Ubuntu distro set as the default default with `wsl -l -v`.
   182  
   183          If you already have WSL2 but don't have an Ubuntu distro, install one with `wsl --install Ubuntu`. 
   184  
   185          If that doesn't work for you, see the [manual installation](https://docs.microsoft.com/en-us/windows/wsl/install-manual) and linked [troubleshooting](https://docs.microsoft.com/en-us/windows/wsl/troubleshooting#installation-issues).
   186          
   187          If you prefer to use another Ubuntu distro, just install it and set it as default. For example, `wsl --set-default Ubuntu-22.04`.
   188  
   189      2. Visit the Microsoft Store and install the updated "Windows Subsystem for Linux", then click *Open*. It will likely prompt you for a username and password for the Ubuntu WSL2 instance it creates.
   190  
   191      3. In *Windows Update Settings* → *Advanced Options* enable *Receive updates for other Microsoft products*. You may want to occasionally run `wsl.exe --update` as well.
   192  
   193      4. Install Docker Desktop. If you already have Chocolatey, run `choco install -y docker-desktop` or [download Docker Desktop from Docker](https://www.docker.com/products/docker-desktop/).
   194      5. Start Docker Desktop. You should now be able to run `docker ps` in PowerShell or Git Bash.
   195      6. In *Docker Desktop* → *Settings* → *Resources* → *WSL2 Integration*, verify that Docker Desktop is integrated with your distro.
   196      7. In an administrative `PowerShell` (5) run [this PowerShell script](https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev_wsl2_docker_desktop.ps1) by executing:
   197  
   198          ```powershell
   199          Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; 
   200          iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev_wsl2_docker_desktop.ps1'))
   201          ```
   202      8. In *Windows Update Settings* → *Advanced Options* enable *Receive updates for other Microsoft products*. You may want to occasionally run `wsl.exe --update` as well.
   203  
   204  
   205      Now you can use the "Ubuntu" terminal app or Windows Terminal to access your Ubuntu distro, which has DDEV and Docker Desktop integrated with it.
   206  
   207      ### WSL2/Docker Desktop Manual Installation
   208  
   209      You can do all of the steps manually of course:
   210  
   211      1. Install [Chocolatey](https://chocolatey.org/install):
   212          ```powershell
   213          Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; 
   214          iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))`
   215          ```
   216      2. In an administrative PowerShell: `choco install -y ddev mkcert`
   217      3. In an administrative PowerShell, run `mkcert -install` and answer the prompt allowing the installation of the Certificate Authority.
   218      4. In an administrative PowerShell, run the command `$env:CAROOT="$(mkcert -CAROOT)"; setx CAROOT $env:CAROOT; If ($Env:WSLENV -notlike "*CAROOT/up:*") { $env:WSLENV="CAROOT/up:$env:WSLENV"; setx WSLENV $Env:WSLENV }`. This will set WSL2 to use the Certificate Authority installed on the Windows side. In some cases it takes a reboot to work correctly.
   219      5. In administrative PowerShell, run the command `wsl --install`. This will install WSL2 and Ubuntu for you. Reboot when this is done.
   220      6. **Docker Desktop for Windows:** If you already have the latest Docker Desktop, configure it in the General Settings to use the WSL2-based engine. Otherwise install the latest Docker Desktop for Windows and select the WSL2-based engine (not legacy Hyper-V) when installing. Install via Chocolatey with `choco install docker-desktop` or it can be downloaded from [desktop.docker.com](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe).  Start Docker. It may prompt you to log out and log in again, or reboot.
   221      7. Go to Docker Desktop’s *Settings* → *Resources* → *WSL integration* → *enable integration for your distro*. Now `docker` commands will be available from within your WSL2 distro.
   222      8. Double-check in PowerShell: `wsl -l -v` should show three distros, and your Ubuntu should be the default. All three should be WSL version 2.
   223      9. Double-check in Ubuntu (or your distro): `echo $CAROOT` should show something like `/mnt/c/Users/<you>/AppData/Local/mkcert`
   224      10. Check that Docker is working inside Ubuntu (or your distro): `docker ps`
   225      11. Open the WSL2 terminal, for example `Ubuntu` from the Windows start menu.
   226      12. Install DDEV using
   227  
   228          ```bash
   229          curl https://apt.fury.io/drud/gpg.key | sudo apt-key add -
   230          echo "deb https://apt.fury.io/drud/ * *" | sudo tee -a /etc/apt/sources.list.d/ddev.list
   231          sudo apt update && sudo apt install -y ddev
   232          ```
   233  
   234      13. In WSL2 run `mkcert -install`.
   235  
   236      You have now installed DDEV on WSL2. If you’re using WSL2 for DDEV (recommended), remember to run all `ddev` commands inside the WSL2 distro.
   237  
   238      To upgrade DDEV in WSL2 Ubuntu, run `apt upgrade ddev` as described in the [Linux installation section](#linux).
   239  
   240      !!!note "Path to certificates"
   241          If you get the prompt `Installing to the system store is not yet supported on this Linux`, you may just need to add `/usr/sbin` to the `$PATH` so that `/usr/sbin/update-ca-certificates` can be found.
   242  
   243      ### Traditional Windows
   244  
   245      If you must use traditional Windows without WSL2, you’ll probably want to enable [Mutagen](performance/#system-requirements) for the best performance.
   246  
   247      * We recommend using [Chocolatey](https://chocolatey.org/). Once installed, you can run `choco install ddev docker-desktop git` from an administrative shell. You can upgrade by running `ddev poweroff && choco upgrade ddev`.
   248      * Each [DDEV release](https://github.com/drud/ddev/releases) includes a Windows installer (`ddev_windows_installer.<version>.exe`). After running that, you can open a new Git Bash, PowerShell, or cmd.exe window and start using DDEV.
   249  
   250      Most people interact with DDEV on Windows using Git Bash, part of the [Windows Git suite](https://git-scm.com/download/win). Although DDEV does work with cmd.exe and PowerShell, it's more at home in Bash. You can install Git Bash with Chocolatey by running `choco install -y git`.
   251  
   252      !!!note "Windows Firefox Trusted CA"
   253  
   254          The `mkcert -install` step on Windows isn’t enough for Firefox.
   255          You need to add the created root certificate authority to the security configuration yourself:
   256  
   257          * Run `mkcert -install` (you can use the shortcut from the Start Menu for that)
   258          * Run `mkcert -CAROOT` to see the local folder used for the newly-created root certificate authority
   259          * Open Firefox Preferences (`about:preferences#privacy`)
   260          * Enter “certificates” into the search box on the top
   261          * Click *View Certificates...*
   262          * Select *Authorities* tab
   263          * Click to *Import...*
   264          * Navigate to the folder where your root certificate authority was stored
   265          * Select the `rootCA.pem` file
   266          * Click to *Open*
   267  
   268          You should now see your CA under `mkcert development CA`.
   269  
   270  === "Gitpod"
   271  
   272      ## Gitpod
   273  
   274      DDEV is fully supported in [Gitpod](https://www.gitpod.io), where you don’t have to install anything at all.
   275  
   276      Choose any of the following methods to launch your project:
   277  
   278      1. [Open any repository](https://www.gitpod.io/docs/getting-started) using Gitpod, run `brew install drud/ddev/ddev`, and use DDEV!
   279          * You can install your web app there, or import a database.
   280          * You may want to implement one of the `ddev pull` provider integrations to pull from a hosting provider or an upstream source.
   281      2. Use the [ddev-gitpod-launcher](https://drud.github.io/ddev-gitpod-launcher/) form to launch a repository.  
   282          You’ll provide a source repository and click a button to open a newly-established environment. You can specify a companion artifacts repository and automatically load `db.sql.gz` and `files.tgz` from it. (More details in the [repository’s README](https://github.com/drud/ddev-gitpod-launcher/blob/main/README.md).)
   283      3. Save the following link to your bookmark bar: <a href="javascript: if %28 %2Fbitbucket%2F.test %28 window.location.host %29 %20 %29 %20%7B%20paths%3Dwindow.location.pathname.split %28 %22%2F%22 %29 %3B%20repo%3D%5Bwindow.location.origin%2C%20paths%5B1%5D%2C%20paths%5B2%5D%5D.join %28 %22%2F%22 %29 %20%7D%3B%20if %28 %2Fgithub.com%7Cgitlab.com%2F.test %28 window.location.host %29  %29 %20%7Brepo%20%3D%20window.location.href%7D%3B%20if%20 %28 repo %29 %20%7Bwindow.location.href%20%3D%20%22https%3A%2F%2Fgitpod.io%2F%23DDEV_REPO%3D%22%20%2B%20encodeURIComponent %28 repo %29 %20%2B%20%22%2CDDEV_ARTIFACTS%3D%22%20%2B%20encodeURIComponent %28 repo %29 %20%2B%20%22-artifacts%2Fhttps%3A%2F%2Fgithub.com%2Fdrud%2Fddev-gitpod-launcher%2F%22%7D%3B">Open in ddev-gitpod</a>.  
   284          It’s easiest to drag the link into your bookmarks. When you’re on a Git repository, click the bookmark to open it with DDEV in Gitpod. It does the same thing as the second option, but it works on non-Chrome browsers and you can use native browser keyboard shortcuts.
   285  
   286      It can be complicated to get private databases and files into Gitpod, so in addition to the launchers, the [`git` provider example](https://github.com/drud/ddev/blob/master/pkg/ddevapp/dotddev_assets/providers/git.yaml.example) demonstrates pulling a database and files without complex setup or permissions. This was created explicitly for Gitpod integration, because in Gitpod you typically already have access to private Git repositories, which are a fine place to put a starter database and files. Although [ddev-gitpod-launcher](https://drud.github.io/ddev-gitpod-launcher/) and the web extension provide the capability, you may want to integrate a Git provider—or one of the [other providers](https://github.com/drud/ddev/tree/master/pkg/ddevapp/dotddev_assets/providers)—for each project.
   287  
   288  === "Codespaces"
   289  
   290      ## GitHub Codespaces
   291  
   292      You can use DDEV in remote [GitHub Codespaces](https://github.com/features/codespaces), skipping the requirement to run Docker locally.
   293  
   294      Start by [creating a new codespace](https://github.com/codespaces/new) for your project, or open an existing one. Next, edit the project configuration to add Docker-in-Docker support along with DDEV. Pick **one** of these methods:
   295  
   296      * Visit your project’s GitHub repository and click the _Code_ dropdown → _Codespaces_ tab → _..._ to the right of “Codespaces” → _Configure dev container_. This will open a `devcontainer.json` file you can edit with the details below.
   297          <img src="./../../../images/codespaces-dev-container.png" alt="GitHub repository’s Code menu, with the Codespaces tab selected to point out the click path described above" width="600" />
   298  
   299      * Open your project’s codespace directly, edit the `.devcontainer/devcontainer.json` file, and rebuild the container with VS Code’s “Codespaces: Rebuild Container” action. (<kbd>⌘</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> on a Mac or <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> on Windows, then search for “rebuild”.)
   300  
   301      Your updated `devcontainer.json` file may differ depending on your project, but you should have `docker-in-docker` and `install-ddev` in the `features` section:
   302  
   303      ```json
   304      {
   305          "image": "mcr.microsoft.com/devcontainers/universal:2",
   306          "features": {
   307              "ghcr.io/devcontainers/features/docker-in-docker:1": {},
   308              "ghcr.io/drud/ddev/install-ddev:latest": {}
   309          },
   310          "portsAttributes": {
   311            "3306": {
   312              "label": "database"
   313            },
   314            "8027": {
   315              "label": "mailhog"
   316            },
   317            "8036": {
   318              "label": "phpmyadmin"
   319            },
   320            "8080": {
   321              "label": "web http"
   322            },
   323            "8443": {
   324              "label": "web https"
   325            }
   326          },
   327          "postCreateCommand": "bash -c 'ddev config global --omit-containers=ddev-router && ddev config --auto && ddev debug download-images'"
   328      }
   329  
   330      ```
   331  
   332      !!!note "Normal Linux installation also works"
   333          You can also install DDEV as if it were on any normal [Linux installation](#linux).
   334  
   335  === "Manual"
   336  
   337      ## Manual
   338  
   339      DDEV is a single executable, so installation on any OS is a matter of copying the `ddev` binary for your architecture into the appropriate system path on your machine.
   340  
   341      * Download and extract the latest [DDEV release](https://github.com/drud/ddev/releases) for your architecture.
   342      * Move `ddev` to `/usr/local/bin` with `mv ddev /usr/local/bin/` (may require `sudo`), or another directory in your `$PATH` as preferred.
   343      * Run `ddev` to test your installation. You should see DDEV’s command usage output.
   344      * As a one-time initialization, run `mkcert -install`, which may require your `sudo` password.  
   345      
   346          If you don’t have `mkcert` installed, download the [latest release](https://github.com/FiloSottile/mkcert/releases) for your architecture and `sudo mv <downloaded_file> /usr/local/bin/mkcert && sudo chmod +x /usr/local/bin/mkcert`.