- Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Tutorial
- Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Server
- Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Download
Overview¶
The next step is to configure WSL so that it knows how to connect to the remote Docker daemon running in Docker for Windows (remember, it's listening on port 2375). If you're not using Docker for Windows and followed Docker Tip #73's guide to create your own VM then you probably did this already which means you can skip the command below. Docker Windows 10 Uninstall hang. GitHub Gist: instantly share code, notes, and snippets.
This page describes using ISLE-DC to launch Islandora as a suite of Docker Containers (ISLE). This is an alternative to the Islandora Ansible Playbook, which creates the Islandora stack on a single virtual machine. At the end of this tutorial, you will have a local development environment, and be able to use Docker to launch, shut down, and edit your environment.
What is ISLE?¶
ISLE, or ISLandora Enterprise, is a community initiative to ease the installation and maintenance of Islandora by using Docker. It was an initiative of the Islandora Collaboration Group, first using Islandora 7.x, and later with Islandora 8.x. The code for the Islandora Enterprise 8 Prototype (ISLE 8, sometimes just ISLE) is now under the purview of the Islandora Foundation. ISLE may also refer to the ISLE system for Islandora 7.
Why use Docker?¶
Docker is a way to separate out the 'state' of your site (i.e. all the content, files, and configurations that you've entered) from the underlying software that runs it (e.g. webserver, database engine, etc). This allows for easier upgrades, faster development, and more flexible deployment.
Where is ISLE 8?¶
ISLE 8 is a suite of Docker containers that run the various components of Islandora required by Islandora Defaults: drupal, fedora, solr, alpaca, crayfish, matomo, etc. The individual containers are created (and automatically pushed to Docker Hub) by ISLE BuildKit.
How do I install ISLE?¶
Install ISLE locally or remotely using the Docker Compose scripts (ISLE-DC) at (Islandora-Devops/isle-dc). These are instructions to pull down and configure the necessary containers from Docker Hub. Unlike the Islandora Playbook, this method does not require Ansible, or (for local installations) VirtualBox. Like the Playbook, it has been optimized for development environments but in theory could be used in production.
These instructions describe using ISLE-DC locally to create a development Islandora sandbox. More detailed configuration options are described in the project's README.
Requirements¶
- A computer that can run Docker (version 19.x+) and has at least 8GB of RAM (ideally 16GB)
- An administrator account
- (Mac OS) Apple Developer Tools
- (Windows) The following setup has been tested:
- Windows 10
- Ubuntu 20.04 running on WSL 2
- GNU make, run
sudo apt update
andsudo apt install make
to install - Docker Desktop for Windows, using the WSL 2 based engine (Settings > General) and with the WSL integration active for Ubuntu (Settings > Resources > WSL integration)
- If using
make dev
, see the README for other requirements.
What are we missing?
Are you, or your computer, new to spinning up development sandboxes? Do you have wisdom about installing make on Windows? We suspect these requirements may be incomplete and your experience would be appreciated at Issue #1640.
Installing Docker¶
Stave%27n%27tabs pro for mac. To see if you have Docker installed, type docker --version
in a terminal.
If you need to install Docker, we recommend using the application Docker Desktop. It provides a GUI for managing Docker container in Windows and MacOS, along with the Docker engine and suite of command-line tools. Linux users don't get a desktop client, but can download the Engine and command-line tools from that same link.
There is also a legacy project called Docker Toolbox which may be of interest if your machine cannot run Docker Desktop, or if you already have it installed.
Memory, Processors, and Swap Requirements
To run ISLE on Docker Desktop, you must increase the resources allocated to the software. See Docker docs on setting resources on Windows (see note on how to allocate/restrict memory when using WSL 2) or setting resources on Mac. Vasilis for mac and cheese.
CPUs (processors): The CPUs allowed to Docker Desktop are still shared with the host machine, so increasing this to the maximum value should allow both the Docker containers and your host machine to run simultaneously.
Memory (RAM): This memory is completely dedicated to Docker while Docker Desktop is running, so do not allocate more than you can spare and still run your host machine. Windows users may not require as much memory for Docker as Mac users. Current suggestions for memory allocated to Docker Desktop are below, but please edit this document if you have new information.
- Sandbox (
make
): 4GB - Development (
make dev
): 8GB - Production or production-like development: 16GB
Swap: Swap space is space borrowed from your hard disk drive to serve as makeshift RAM as needed. If you cannot provide as much RAM as you would like, increase this as is reasonable given your free disk space.
Launching Islandora with Docker¶
Summary: Using git, clone the isle-dc project. In that directory, enter the command make
(or make dev
- see note) to build the docker infrastructure. Then use the command docker-compose up -d
to start the containers.
ISLE-DC variants: make
vs make dev
The make
command alone will spin up a sandbox-like version of ISLE, but only with a front end. The code files will be inaccessible, and you will not be able to install additional modules or themes. The make dev
command creates a full-fleged development environment. It will copy the active Drupal codebase locally in a way that is also live to the ISLE site. This method takes longer (and may require multiple retries if your internet connection is spotty) but is required if you will be testing pull requests or writing code.
Results of make
:
Troubleshooting - Docker Versions
If you get an error such as: ERROR: Version in './docker-compose.activemq.yml' is unsupported.
, then you need to upgrade Docker. Enter the command make clean
before re-attempting to make
.
Troubleshooting - re-attempting make
If make
fails for any reason, enter make clean
before attempting to make
again. If not, you may see an error such as: ERROR: Top level object in './docker-compose.yml' needs to be an object not ''.
Troubleshooting - docker containers exit without warning
If you notice some Docker containers drop (exited(0)), and (in Docker Desktop) the isle-dc app icon is yellow instead of green, try increasing the resources allocated to Docker (see note above).
Development version - access the codebase
If you used make dev
, then you will have a new directory in the current (isle-dc) directory named codebase
, containing the live Drupal root folder (containing your Drupal's composer files and the web/ subdirectory).
Once make
has successfully completed, launch the ISLE containers using docker-compose up
. The -d
flag allows you to return to using the command line. Without it, your shell will be stuck in the docker-compose
process as long as the containers are running.
Troubleshooting - connection timed out (Mac).
If you are using Docker Desktop for Mac, and get timeout errors when spinning up the containers (during docker-compose up -d
or during make dev
) such as this:
ERROR: for isle-dc_mariadb_1 UnixHTTPConnectionPool(host='localhost', port=None): Read timed out. (read timeout=480)
you can try quitting Docker completely (make sure there is no whale icon in your top toolbar - may need to select 'Quit' from the whale icon itself) and then restart Docker.
Visiting your Islandora site¶
Direct a browser to https://islandora.traefik.me/. If your containers are still 'spinning up', you will see a white screen with the words 'Bad Gateway'. This often lasts 2-5 minutes, and should be shorter for subsequent launches. If it takes more than a few minutes, check to make sure that none of your containers have failed to launch (see note above on 'Troubleshooting - docker containers exit without warning'). When all containers are ready, you should see a basic Drupal login screen.
To log in:
- username: admin
- password: password
Note
docker logs -tf isle-dc_drupal_1
shows Docker logs for the 'drupal' container, which will continue to have new log entries as long as the drupal box is still starting up. When it gets to confd using 'env' backend
, you're done. docker-compose logs
is like a firehose, showing the log messages from all containers.
Spinning down your Islandora site¶
To shut down the containers without destroying your site, use docker-compose down
. To also destroy your 'state' (i.e. your content, your database, your files), use docker-compose down -v
.
Editing Code in Docker¶
If you used make dev
then the drupal root folder is in a new directory in the isle-dc folder named codebase
. This is live and editable in whatever development environment you would like. If you just did make
, you will need to spin down your containers with -v
to destroy your state before starting a new one with make dev
.
Editing code for the back-end processes (alpaca, milliner, etc) is more complicated. Please ask on the #isle Slack channel and help us improve this documentation!
Testing a Pull Request¶
Islandora modules in the codebase/web/contrib/modules
folder are already set up with git
and the origin
remote is the canonical Islandora repository. You can follow the command-line instructions for testing pull requests available on Github. When finished, don't forget to git checkout main
(or the default branch if not named main) so you can pull new code.
Updating ISLE¶
Documentation to come - see Issue #121
Drupal Updates¶
to come
Module Updates (non-Islandora)¶
to come
Module Updates (Islandora)¶
to come
Backend Providers (solr, mariadb, etc)¶
to come
Updating the whole isle-dc repo¶
to come
Estimated reading time: 4 minutes
Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Tutorial
Docker Desktop for Mac provides several networking features to make iteasier to use.
Features
VPN Passthrough
Docker Desktop for Mac's networking can work when attached to a VPN. To do this,Docker Desktop for Mac intercepts traffic from the containers and injects it intoMac as if it originated from the Docker application.
Port Mapping
Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Server
When you run a container with the -p
argument, for example:
Docker Desktop for Mac makes whatever is running on port 80 in the container (inthis case, nginx
) available on port 80 of localhost
. In this example, thehost and container ports are the same. What if you need to specify a differenthost port? If, for example, you already have something running on port 80 ofyour host machine, you can connect the container to a different port:
Now, connections to localhost:8000
are sent to port 80 in the container. Thesyntax for -p
is HOST_PORT:CLIENT_PORT
.
HTTP/HTTPS Proxy Support
See Proxies.
Known limitations, use cases, and workarounds
Following is a summary of current limitations on the Docker Desktop for Macnetworking stack, along with some ideas for workarounds.
There is no docker0 bridge on macOS
Because of the way networking is implemented in Docker Desktop for Mac, you cannot see adocker0
interface on the host. This interface is actually within the virtualmachine.
I cannot ping my containers
These instructions describe using ISLE-DC locally to create a development Islandora sandbox. More detailed configuration options are described in the project's README.
Requirements¶
- A computer that can run Docker (version 19.x+) and has at least 8GB of RAM (ideally 16GB)
- An administrator account
- (Mac OS) Apple Developer Tools
- (Windows) The following setup has been tested:
- Windows 10
- Ubuntu 20.04 running on WSL 2
- GNU make, run
sudo apt update
andsudo apt install make
to install - Docker Desktop for Windows, using the WSL 2 based engine (Settings > General) and with the WSL integration active for Ubuntu (Settings > Resources > WSL integration)
- If using
make dev
, see the README for other requirements.
What are we missing?
Are you, or your computer, new to spinning up development sandboxes? Do you have wisdom about installing make on Windows? We suspect these requirements may be incomplete and your experience would be appreciated at Issue #1640.
Installing Docker¶
Stave%27n%27tabs pro for mac. To see if you have Docker installed, type docker --version
in a terminal.
If you need to install Docker, we recommend using the application Docker Desktop. It provides a GUI for managing Docker container in Windows and MacOS, along with the Docker engine and suite of command-line tools. Linux users don't get a desktop client, but can download the Engine and command-line tools from that same link.
There is also a legacy project called Docker Toolbox which may be of interest if your machine cannot run Docker Desktop, or if you already have it installed.
Memory, Processors, and Swap Requirements
To run ISLE on Docker Desktop, you must increase the resources allocated to the software. See Docker docs on setting resources on Windows (see note on how to allocate/restrict memory when using WSL 2) or setting resources on Mac. Vasilis for mac and cheese.
CPUs (processors): The CPUs allowed to Docker Desktop are still shared with the host machine, so increasing this to the maximum value should allow both the Docker containers and your host machine to run simultaneously.
Memory (RAM): This memory is completely dedicated to Docker while Docker Desktop is running, so do not allocate more than you can spare and still run your host machine. Windows users may not require as much memory for Docker as Mac users. Current suggestions for memory allocated to Docker Desktop are below, but please edit this document if you have new information.
- Sandbox (
make
): 4GB - Development (
make dev
): 8GB - Production or production-like development: 16GB
Swap: Swap space is space borrowed from your hard disk drive to serve as makeshift RAM as needed. If you cannot provide as much RAM as you would like, increase this as is reasonable given your free disk space.
Launching Islandora with Docker¶
Summary: Using git, clone the isle-dc project. In that directory, enter the command make
(or make dev
- see note) to build the docker infrastructure. Then use the command docker-compose up -d
to start the containers.
ISLE-DC variants: make
vs make dev
The make
command alone will spin up a sandbox-like version of ISLE, but only with a front end. The code files will be inaccessible, and you will not be able to install additional modules or themes. The make dev
command creates a full-fleged development environment. It will copy the active Drupal codebase locally in a way that is also live to the ISLE site. This method takes longer (and may require multiple retries if your internet connection is spotty) but is required if you will be testing pull requests or writing code.
Results of make
:
Troubleshooting - Docker Versions
If you get an error such as: ERROR: Version in './docker-compose.activemq.yml' is unsupported.
, then you need to upgrade Docker. Enter the command make clean
before re-attempting to make
.
Troubleshooting - re-attempting make
If make
fails for any reason, enter make clean
before attempting to make
again. If not, you may see an error such as: ERROR: Top level object in './docker-compose.yml' needs to be an object not ''.
Troubleshooting - docker containers exit without warning
If you notice some Docker containers drop (exited(0)), and (in Docker Desktop) the isle-dc app icon is yellow instead of green, try increasing the resources allocated to Docker (see note above).
Development version - access the codebase
If you used make dev
, then you will have a new directory in the current (isle-dc) directory named codebase
, containing the live Drupal root folder (containing your Drupal's composer files and the web/ subdirectory).
Once make
has successfully completed, launch the ISLE containers using docker-compose up
. The -d
flag allows you to return to using the command line. Without it, your shell will be stuck in the docker-compose
process as long as the containers are running.
Troubleshooting - connection timed out (Mac).
If you are using Docker Desktop for Mac, and get timeout errors when spinning up the containers (during docker-compose up -d
or during make dev
) such as this:
ERROR: for isle-dc_mariadb_1 UnixHTTPConnectionPool(host='localhost', port=None): Read timed out. (read timeout=480)
you can try quitting Docker completely (make sure there is no whale icon in your top toolbar - may need to select 'Quit' from the whale icon itself) and then restart Docker.
Visiting your Islandora site¶
Direct a browser to https://islandora.traefik.me/. If your containers are still 'spinning up', you will see a white screen with the words 'Bad Gateway'. This often lasts 2-5 minutes, and should be shorter for subsequent launches. If it takes more than a few minutes, check to make sure that none of your containers have failed to launch (see note above on 'Troubleshooting - docker containers exit without warning'). When all containers are ready, you should see a basic Drupal login screen.
To log in:
- username: admin
- password: password
Note
docker logs -tf isle-dc_drupal_1
shows Docker logs for the 'drupal' container, which will continue to have new log entries as long as the drupal box is still starting up. When it gets to confd using 'env' backend
, you're done. docker-compose logs
is like a firehose, showing the log messages from all containers.
Spinning down your Islandora site¶
To shut down the containers without destroying your site, use docker-compose down
. To also destroy your 'state' (i.e. your content, your database, your files), use docker-compose down -v
.
Editing Code in Docker¶
If you used make dev
then the drupal root folder is in a new directory in the isle-dc folder named codebase
. This is live and editable in whatever development environment you would like. If you just did make
, you will need to spin down your containers with -v
to destroy your state before starting a new one with make dev
.
Editing code for the back-end processes (alpaca, milliner, etc) is more complicated. Please ask on the #isle Slack channel and help us improve this documentation!
Testing a Pull Request¶
Islandora modules in the codebase/web/contrib/modules
folder are already set up with git
and the origin
remote is the canonical Islandora repository. You can follow the command-line instructions for testing pull requests available on Github. When finished, don't forget to git checkout main
(or the default branch if not named main) so you can pull new code.
Updating ISLE¶
Documentation to come - see Issue #121
Drupal Updates¶
to come
Module Updates (non-Islandora)¶
to come
Module Updates (Islandora)¶
to come
Backend Providers (solr, mariadb, etc)¶
to come
Updating the whole isle-dc repo¶
to come
Estimated reading time: 4 minutes
Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Tutorial
Docker Desktop for Mac provides several networking features to make iteasier to use.
Features
VPN Passthrough
Docker Desktop for Mac's networking can work when attached to a VPN. To do this,Docker Desktop for Mac intercepts traffic from the containers and injects it intoMac as if it originated from the Docker application.
Port Mapping
Failed Port Is Already Allocated Issue 1114 Docker For Mac Github Server
When you run a container with the -p
argument, for example:
Docker Desktop for Mac makes whatever is running on port 80 in the container (inthis case, nginx
) available on port 80 of localhost
. In this example, thehost and container ports are the same. What if you need to specify a differenthost port? If, for example, you already have something running on port 80 ofyour host machine, you can connect the container to a different port:
Now, connections to localhost:8000
are sent to port 80 in the container. Thesyntax for -p
is HOST_PORT:CLIENT_PORT
.
HTTP/HTTPS Proxy Support
See Proxies.
Known limitations, use cases, and workarounds
Following is a summary of current limitations on the Docker Desktop for Macnetworking stack, along with some ideas for workarounds.
There is no docker0 bridge on macOS
Because of the way networking is implemented in Docker Desktop for Mac, you cannot see adocker0
interface on the host. This interface is actually within the virtualmachine.
I cannot ping my containers
Docker Desktop for Mac can't route traffic to containers.
Per-container IP addressing is not possible
The docker (Linux) bridge network is not reachable from the macOS host.
Use cases and workarounds
There are two scenarios that the above limitations affect:
I want to connect from a container to a service on the host
The host has a changing IP address (or none if you have no network access). We recommend that you connect to the special DNS namehost.docker.internal
which resolves to the internal IP address used by thehost. This is for development purpose and will not work in a production environment outside of Docker Desktop for Mac.
You can also reach the gateway using gateway.docker.internal
.
If you have installed Python on your machine, use the following instructions as an example to connect from a container to a service on the host:
Run the following command to start a simple HTTP server on port 8000.
python -m http.server 8000
If you have installed Python 2.x, run
python -m SimpleHTTPServer 8000
.Now, run a container, install
curl
, and try to connect to the host using the following commands:
I want to connect to a container from the Mac
Port forwarding works for localhost
; --publish
, -p
, or -P
all work.Ports exposed from Linux are forwarded to the host.
Our current recommendation is to publish a port, or to connect from anothercontainer. This is what you need to do even on Linux if the container is on anoverlay network, not a bridge network, as these are not routed.
The command to run the nginx
webserver shown in Getting Startedis an example of this.
To clarify the syntax, the following two commands both expose port 80
on thecontainer to port 8000
on the host:
To expose all ports, use the -P
flag. For example, the following commandstarts a container (in detached mode) and the -P
exposes all ports on thecontainer to random ports on the host.
See the run command for more details onpublish options used with docker run
.