From 8f5cb358023b32947d81bddd12681ccf2e344cac Mon Sep 17 00:00:00 2001 From: Wilbur Ince Date: Sat, 28 Dec 2024 14:17:20 -0600 Subject: [PATCH 1/5] Reverting back to our original, but updated readme document for now. --- README.md | 244 +++++++++++++----------------------------------------- 1 file changed, 57 insertions(+), 187 deletions(-) diff --git a/README.md b/README.md index 6b16c69..54b836a 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,73 @@ -# What is Backdrop? - -_**TL;DR: Backdrop is an exciting and promising way forward for organizations seeking a means of leaving legacy Drupal behind in a way that preserves their Drupal-related investments of time, energy, people and money.**_ - -Backdrop is a web application development framework most commonly configured as a Content Management System (CMS) for use by: - -- Small & Medium Sized Enterprises (SME) -- Governments & Government Departments -- Non-Governmental Organizations (NGO) -- Non-Profit Organizations (NPO) -- Educational Institutions (EI). - -Backdrop started off as a "fork" of an immensely popular Drupal 7. The genesis of the Backdrop CMS Project was the release of Drupal 8. That release (and every subsequent Drupal release thereafter) introduced an explosion in uncertainty, complexity and cost. Some of the key goals of Backdrop are predictability, reliability, controlled complexity and maximum compatibility with the code base of Drupal 7 - especially in terms of compatibility with Drupal 7 contributed modules and themes. There are over 16,000+ contributed Drupal 7 modules and themes, representing a near-infinite range of solutions. - -Since 2013, Backdrop has remained true to its goals. Now, a Backdrop conversion can take a small fraction of the time and expense involved with migrating to a different CMS (usually Wordpress), using a cloud-based provider (WIX or Shopify) or even upgrading to the latest version of Drupal. Many organizations have already leveraged the power of Backdrop to move away from legacy Drupal, especially Drupal 7, in a way that they feel is the fastest, easiest and least expensive way possible. - -The Backdrop Project was started over a decade ago. To date, its story is marked by a string of successes: It is being continually improved. It offers the latest technologies. New versions of Backdrop are released in a regular and methodical way. Backdrop releases are supported for a very long time. New (and converted) Backdrop modules and themes are arriving ever more frequently. It has a dedicated, mature, experienced and highly professional project team. - -The latest edition of Backdrop is **1.29.2**. +# Docker Official Image -_(a full list of every docker image available for Backdrop, including legacy and alternative versions, appears at the end of this document)_ +https://github.com/docker-library/official-images/blob/master/library/backdrop -# What is Docker? -According to Amazon, Docker is: +# Supported tags and respective `Dockerfile` links -_"A software platform that allows you to build, test, and deploy applications quickly. Docker packages software into standardized units called containers that have everything the software needs to run including libraries, system tools, code, and runtime."_ +- [`1.29.2-apache`, `1.29.2`, `1-apache`, `1` (*1/apache/Dockerfile*)](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) +- [`1.29.2-fpm`, `1-fpm` (*1/fpm/Dockerfile*)](https://github.com/kalabox/backdrop-docker/blob/master/1/fpm/Dockerfile) -# What are the Backdrop Docker Official Image(s)? -The Backdrop Docker Official Images is a collection of docker images intended to enable almost anyone to quickly and easily install Backdrop for evaluation purposes. The intent of this documentation, along with the Backdrop Docker Official Images collection, is to empower regular people to be able to install Docker and use it to "spin up" an evaluation instance of Backdrop with a minimal investment of their time and money. +[![](https://badge.imagelayers.io/kalabox/backdrop:latest.svg)](https://imagelayers.io/?images=kalabox/backdrop:latest 'Get your own badge on imagelayers.io') -# Backdrop Current Edition (latest) -The current edition of Backdrop is **1.29.2**. +# What is Backdrop? -## MAIN -The **MAIN** edition of Backdrop is the one that is downloaded by Docker when nothing more specific is provided, or when special or reserved tags are used (`latest` or `backdrop`). This is the **DEFAULT** version of Backdrop that Docker installs. +Backdrop is a web application development framework frequenty deployed in the guise of a Content Management System (or "website") for use by: +- Primary, Secondary and Tertiary Educational Institutions +- National, Regional and Municipal Governments +- Small & Medium Sized Enterprises +- Non-Governmental Organizations +- Non-Profit Organizations -### ALTERNATIVE -The ALTERNATIVE edition(s) of Backdrop must be speci +![logo](https://backdropcms.org/files/inline-images/Backdrop-Logo-Vertical_0.png) -_(a complete list of MAIN & ALTERNATIVE Backdrop editions, including legacy editions, editions appears at the end of this document)_ +# How to use this image -# Tags +The basic pattern for starting a `backdrop` instance is: -## Apache 2 (apache) +```console +docker run --name some-backdrop --link some-mysql:mysql -d backdrop/backdrop +``` -[`latest`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) -[`backdrop`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) -[`1.29.2-apache`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) -[`1.29.2`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) -[`1-apache`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) -[`1`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) +The following environment variables are also honored for configuring your Backdrop CMS instance: -Source [*Dockerfile*](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) - -## FastCGI Process Manager (fpm) -[`1.29.2-fpm`](https://github.com/kalabox/backdrop-docker/blob/master/1/fpm/Dockerfile) -[`1-fpm`](https://github.com/kalabox/backdrop-docker/blob/master/1/fpm/Dockerfile) +- `-e BACKDROP_DB_HOST=...` (defaults to the IP and port of the linked `mysql` container) +- `-e BACKDROP_DB_USER=...` (defaults to "root") +- `-e BACKDROP_DB_PASSWORD=...` (defaults to the value of the `MYSQL_ROOT_PASSWORD` environment variable from the linked `mysql` container) +- `-e BACKDROP_DB_NAME=...` (defaults to "backdrop") +- `-e BACKDROP_DB_PORT=...` (defaults to 3306) +- `-e BACKDROP_DB_DRIVER=...` (defaults to "mysql") -Source [*Dockerfile*](https://github.com/kalabox/backdrop-docker/blob/master/1/fpm/Dockerfile) +The `BACKDROP_DB_NAME` **must already exist** on the given MySQL server. Check out the [official mysql image](https://hub.docker.com/_/mysql/) for more info on spinning up a DB. -# Use -The fastest and easiest way to "spin up" any of the above-mentioned Backdrop containers with docker is to: +If you'd like to be able to access the instance from the host without the container's IP, standard port mappings can be used: - 1) Install docker on a host system - 2) Create a named directory to marshal docker-related Backdrop assets - 3) Create a docker startup file that references a specific Backdrop docker image - 4) Launch docker in such a way that it processes the startup file +```console +docker run --name some-backdrop --link some-mysql:mysql -p 8080:80 -d backdrop/backdrop +``` -## Step 1: Install docker on a host system -[Docker's installation instructions for Windows, Mac and Linux](https://www.docker.com/get-started) +Then, access it via `http://localhost:8080` or `http://host-ip:8080` in a browser. -## Step 2: Create a named directory to marshal docker-related Backdrop assets -In this case we will create a directory named `backdrop-eval` to help assemble together some Backdrop-related docker assets +If you'd like to use an external database instead of a linked `mysql` container, specify the hostname and port with `BACKDROP_DB_HOST`/`BACKDROP_DB_PORT` along with the password in `BACKDROP_DB_PASSWORD` and the username in `BACKDROP_DB_USER` (if it is something other than `root`): -`md backdrop-eval` +```console +docker run --name some-backdrop \ + -e BACKDROP_DB_HOST=10.1.2.3 \ + -e BACKDROP_DB_PORT=10432 \ + -e BACKDROP_DB_USER=... \ + -e BACKDROP_DB_PASSWORD=... \ + -d backdrop/backdrop +``` -`cd backdrop-eval` +## ... via [`docker-compose`](https://github.com/docker/compose) -## Step 3: Create a docker startup file that references a specific Backdrop docker image -In the `backdrop-eval` directory, create `compose.yml` file with the following contents: +Example `docker-compose.yml` for `backdrop`: ```yaml services: backdrop: - build: - context: ./1/apache + image: backdrop ports: - - 8088:80 + - 8080:80 environment: BACKDROP_DB_HOST: db BACKDROP_DB_USER: backdrop @@ -100,144 +82,32 @@ services: MYSQL_DATABASE: backdrop ``` -## Step 4: Launch docker in such a way that it processes the startup file -While in the `docker-eval` directory, enter the following command: - -`docker compose up` - -This command instructs docker to process the `compose.yml` file. The screen should immediately begin to fill with startup messages as docker composes the Backdrop runtime environment. After a minute or so, the pace of new messages should settle down, with just status messages being displayed. At this point the Backdrop installation screen should be accessible via a web browser. +Run `docker-compose up`, wait for it to initialize completely, and visit `http://localhost:8080` or `http://host-ip:8080`. -### Accessing a remote docker container -If the web browser is running on a different machine than the one running docker, the Backdrop installation should be accessible at: +## Adding additional libraries / extensions -`http://{host-ip}:8080`. - -Where `{host-ip}` is the IP address of the machine running docker. - -### Accessing a local docker container -If the web browser is running on the same machine as docker, the Backdrop installation should be accessible at: - -`http://localhost:8080` - -### 'compose.yml` Embedded Credentials -The credentials embedded in the `compose.yml` will be required in the Backdrop installation routine: - -``` -User: backdrop -Password: backdrop -Database: backdrop -``` +This image does not provide any additional PHP extensions or other libraries, even if they are required by popular plugins. There are an infinite number of possible plugins, and they potentially require any extension PHP supports. Including every PHP extension that exists would dramatically increase the image size. -## How to validate the docker-based backdrop runtime environment -Validating that backdrop indeed constructed a valid runtime environment may be accomplished with the following command: - -``` -docker ps -``` - -The resulting listing should include TWO (2) docker containers, one for the database server (db), one for the CMS (backdrop). - -## How to access the docker-based backdrop runtime environment -Accessing the docker container may be accomplished with the following command: - -``` -docker exec -it backdrop bash -``` - -## Trying out other docker images -The above `compose.yml` specifically references the `backdrop/backdrop` docker image. +If you need additional PHP extensions, you'll need to create your own image `FROM` this one. The [documentation of the `php` image](https://github.com/docker-library/docs/blob/master/php/README.md#how-to-install-more-php-extensions) explains how to compile additional extensions. Additionally, the [`drupal:7` Dockerfile](https://github.com/docker-library/drupal/blob/bee08efba505b740a14d68254d6e51af7ab2f3ea/7/Dockerfile#L6-9) has an example of doing this. -This is just an example to help get you started. Once you are familiar with how to "spin up" a docker image, there is nothing to stop you from trying out different docker images to find the one you like the best. A complete listing of all available backdrop docker images is available at the end of this document. +The following Docker Hub features can help with the task of keeping your dependent images up-to-date: -# About Backdrop -![logo](https://backdropcms.org/files/inline-images/Backdrop-Logo-Vertical_0.png) +- [Automated Builds](https://docs.docker.com/docker-hub/builds/) let Docker Hub automatically build your Dockerfile each time you push changes to it. +- [Repository Links](https://docs.docker.com/docker-hub/builds/#repository-links) can ensure that your image is also rebuilt any time `drupal` is updated. # License View [license information](https://www.drupal.org/licensing/faq) for the software contained in this image. -# Feedback - -## Issue Queue(s) -- [Backdrop CMS Core Issue Queue](https://github.com/backdrop/backdrop-issues/issues) -- [Backdrop CMS Contrib at Github.com](https://github.com/backdrop-contrib) - Each contrib project has it's own issue queue. +# User Feedback ## Documentation - [Backdrop CMS Documentation](https://docs.backdropcms.org/) +## Issues +- [Backdrop CMS Core Issue Queue](https://github.com/backdrop/backdrop-issues/issues) +- [Backdrop CMS Contrib at Github.com](https://github.com/backdrop-contrib) - Each contrib project has it's own issue queue. + ## Contributing - [Contribute to the Backdrop CMS Open Source Project](https://docs.backdropcms.org/documentation/contributors-guide) -## Official Docker Image - -https://github.com/docker-library/official-images/blob/master/library/backdrop - -# Expert Mode - -## Installing additional libraries & extensions -These images do not provide any additional PHP extensions or other libraries, even if they are required by popular plugins. There are an infinite number of possible plugins, and they potentially require any extension PHP supports. Including every PHP extension that exists would dramatically increase the image size. - -## Generating your own docker image(s) -If you need additional PHP extensions, you'll need to create your own image `FROM` this one. The [documentation of the `php` image](https://github.com/docker-library/docs/blob/master/php/README.md#how-to-install-more-php-extensions) explains how to compile additional extensions. Additionally, the [`drupal:7` Dockerfile](https://github.com/docker-library/drupal/blob/bee08efba505b740a14d68254d6e51af7ab2f3ea/7/Dockerfile#L6-9) has an example of doing this. - -The following Docker Hub features can help with the task of keeping your dependent images up-to-date: - -- [Automated Builds](https://docs.docker.com/docker-hub/builds/) let Docker Hub automatically build your Dockerfile each time you push changes to it. -- [Repository Links](https://docs.docker.com/docker-hub/builds/#repository-links) can ensure that your image is also rebuilt any time `drupal` is updated. - -## Launching backdrop manually using `docker run` commands - -### MySQL -NOTE: A pre-configured database server must already exist before a backdrop container can be launched. - -Check out the [official mysql image](https://hub.docker.com/_/mysql/) for more info on spinning up a DB. - -## Backdrop -The basic pattern for starting a `backdrop` instance (given that the `BACKDROP_DB_NAME` **already exists** on a running MySQL server container) is: - -```console -docker run --name some-backdrop --link some-mysql:mysql -d backdrop/backdrop -``` - -The following environment variables are also honored for configuring your Backdrop CMS instance: - -- `-e BACKDROP_DB_HOST=...` (defaults to the IP and port of the linked `mysql` container) -- `-e BACKDROP_DB_USER=...` (defaults to "root") -- `-e BACKDROP_DB_PASSWORD=...` (defaults to the value of the `MYSQL_ROOT_PASSWORD` environment variable from the linked `mysql` container) -- `-e BACKDROP_DB_NAME=...` (defaults to "backdrop") -- `-e BACKDROP_DB_PORT=...` (defaults to 3306) -- `-e BACKDROP_DB_DRIVER=...` (defaults to "mysql") - - -If you'd like to be able to access the instance from the host without the container's IP, standard port mappings can be used: - -```console -docker run --name some-backdrop --link some-mysql:mysql -p 8080:80 -d backdrop/backdrop -``` - -Then, access it via `http://localhost:8080` or `http://host-ip:8080` in a browser. - -If you'd like to use an external database instead of a linked `mysql` container, specify the hostname and port with `BACKDROP_DB_HOST`/`BACKDROP_DB_PORT` along with the password in `BACKDROP_DB_PASSWORD` and the username in `BACKDROP_DB_USER` (if it is something other than `root`): - -```console -docker run --name some-backdrop \ - -e BACKDROP_DB_HOST=10.1.2.3 \ - -e BACKDROP_DB_PORT=10432 \ - -e BACKDROP_DB_USER=... \ - -e BACKDROP_DB_PASSWORD=... \ - -d backdrop/backdrop -``` - -# Backdrop Dockerfile archive -_([please review release notes before deploying](https://github.com/backdrop/backdrop/releases))_ -## 1.30.0 (coming Januaray 2025) -`1.30.2-apache` -`1.30.2-fpm` - -## 1.29.2 -[`1.29.2-apache`](https://github.com/kalabox/backdrop-docker/blob/master/1/apache/Dockerfile) -[`1.29.2-fpm`](https://github.com/kalabox/backdrop-docker/blob/master/1/fpm/Dockerfile) - -## 1.29.1 -`1.29.1-apache` -`1.29.1-fpm` From df3df80092e9fee338f910c9708528910e45e620 Mon Sep 17 00:00:00 2001 From: Wilbur Ince Date: Thu, 2 Jan 2025 13:24:11 -0600 Subject: [PATCH 2/5] Update Dockerfile --- 1/apache/Dockerfile | 2 -- 1 file changed, 2 deletions(-) diff --git a/1/apache/Dockerfile b/1/apache/Dockerfile index d227d60..1ce9aea 100644 --- a/1/apache/Dockerfile +++ b/1/apache/Dockerfile @@ -24,7 +24,5 @@ RUN curl -fSL "https://github.com/backdrop/backdrop/archive/refs/tags/${BACKDROP # Add custom entrypoint to set BACKDROP_SETTINGS correctly COPY docker-entrypoint.sh /entrypoint.sh -EXPOSE 80 - ENTRYPOINT ["/entrypoint.sh"] CMD ["apache2-foreground"] From b489216d9fc6b4a6f969cb0f4fa46eba72edf433 Mon Sep 17 00:00:00 2001 From: Wilbur Ince Date: Thu, 2 Jan 2025 13:27:24 -0600 Subject: [PATCH 3/5] Removing expose command from fpm dockerfile, this is not appropriate --- 1/fpm/Dockerfile | 2 -- 1 file changed, 2 deletions(-) diff --git a/1/fpm/Dockerfile b/1/fpm/Dockerfile index a813df0..04dbdae 100644 --- a/1/fpm/Dockerfile +++ b/1/fpm/Dockerfile @@ -22,7 +22,5 @@ RUN curl -fSL "https://github.com/backdrop/backdrop/archive/${BACKDROP_VERSION}. # Add custom entrypoint to set BACKDROP_SETTINGS correctly COPY docker-entrypoint.sh /entrypoint.sh -EXPOSE 80 - ENTRYPOINT ["/entrypoint.sh"] CMD ["php-fpm"] From 76408bf7ef772f87e07b87231d887160d23f75f2 Mon Sep 17 00:00:00 2001 From: Orwa Diraneyya <107997002+diraneyya@users.noreply.github.com> Date: Fri, 3 Jan 2025 14:46:20 +0100 Subject: [PATCH 4/5] Update README.md added various improvements. --- README.md | 130 +++++++++++++++++++++++++++--------------------------- 1 file changed, 65 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 2a19ac2..f3d8f5d 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,10 @@ The process of "spinning up" Backdrop as a Docker container application involves 1) Ensuring Docker is installed on the host machine 2) Creating a named directory to hold Docker configuration file(s) - 3) Creating a new docker startup file referencing a Backdrop Docker Image - 4) Launching docker in such a way that it processes the new docker startup file + 3) Creating a new Docker startup file (also called: a _Docker Compose_ file) referencing a Backdrop Docker Image + 4) Launching Docker in such a way that it processes the new Docker startup file (using the command `docker compose`) -## Step 1: Ensure Docker is Installed on the Host Machine +## Step 1: Ensure Docker is Installed on the Host Machine [Click here to see Docker's installation instructions for Windows, Mac and Linux](https://www.docker.com/get-started) The following example checks for the existence of Docker on a Linux host: @@ -24,88 +24,71 @@ docker -v Docker version 27.4.1, build b9d17ea ``` -## Step 2: Create a Named Directory to Hold Docker Configuration File(s) -The following example creates a directory named `backdrop-eval` for the purpose of holding Docker configuration file(s) on a Linux host +## Step 2: Create a Named Directory to Hold Docker Configuration File(s) -``` -md /var/www/backdrop-eval +The following example creates a directory named `backdrop-eval` for the purpose of holding Docker configuration file(s) on a Linux host (the folder is created inside of the current directory which could be the home of the logged-in user or another directory within it). -cd /var/www/backdrop-eval +``` +mkdir backdrop-eval +cd backdrop-eval ``` -## Step 3: Create a New Docker Startup File Referencing a Backdrop Docker Image -Docker usually requires configuration information to be able to successfully "spin up" an image. This is especially true in the case of Backdrop, because **two** containers are involved; MySQl and Backdrop. Backdrop requires the availability of a MySQL server in order to work. Docker accommodates this somewhat complicated situation by way of the `compose.yml` file, which contains all of the custom settings needed to help Docker set up the two containers, and get them to interoperate. +## Step 3: Create a New Docker Startup (i.e. _Docker compose_) File Referencing a Backdrop Docker Image +Docker offers a way to launch docker images that need to work together as an application. Such files are called _Docker compose_ files and are usually used when more than one Docker image is needed by the application. In the case of Backdrop, it is not sufficient to run the Backdrop Docker image which contains an Apache PHP application. Additionally, a MySQL database server is also needed. Hence, to "spin up" the Backdrop application (which involves running these two images), a Docker compose file is conveniently used. -The following example `/var/www/backdrop-eval/compose.yml` file ensures that the Backdrop Docker image launches correctly: +This is the `compose.yml` file, which contains all the settings needed to help Docker set up ad run the two containers, in a manner that allows them to interoperate as an application. -``` +The following example `compose.yml` file (located in the named directory created in Step 2) will conveniently _orchestrate_ the launch of the Backdrop and the MySQL Docker images: +``` services: - backdrop: - image: backdrop:latest - container_name: backdrop - ports: - - 8088:80 - environment: - BACKDROP_DB_HOST: mysql - BACKDROP_DB_USER: backdrop - BACKDROP_DB_PASSWORD: backdrop mysql: - image: mysql:latest - container_name: mysql - environment: - MYSQL_USER: backdrop - MYSQL_PASSWORD: backdrop - MYSQL_DATABASE: backdrop - MYSQL_ALLOW_EMPTY_PASSWORD: 'yes' ``` +> [!NOTE] +> The Docker compose file above is a bare minimum for testing Backdrop locally. In the case of running Backdrop on a server using Docker, which is often described as "production", the file will likely need to be modified. The modifications involved are beyond the scope of this README file. + ## Step 4: Launch docker in Such a Way That it Processes the New Docker Startup File + While in the `docker-eval` directory, enter the following command: ``` docker compose up ``` -This command instructs docker to process the `compose.yml` file in the current directory. +This command instructs Docker to process the `compose.yml` startup file located in the same directory. -The screen should immediately begin to fill with startup messages as docker composes the Backdrop runtime environment. After a minute or so, the pace of new messages should settle down, with just status messages being displayed. At this point the Backdrop installation screen should be accessible via a web browser. +The screen should immediately begin to fill with startup messages as docker processes the compose file and launches the service Docker images referenced within it. After a minute or so, the pace of new messages should settle down, with just status messages being displayed (which are preceded by `backdrop` or `mysql`, referring to the service from which the status message is being emitted). At this point, the Backdrop installation screen should be accessible via a web browser. -# How to Access Backdrop in a Local Docker Container -If the web browser is running on **the same machine** as docker, Backdrop should be accessible at: +## Next Steps/Troubleshooting -``` -http://localhost:8080 -``` +### How to Access Backdrop in a Local Docker Container -# How to Access Backdrop in a Remote Docker Container -If the web browser is running on **a different machine** than the one running docker, Backdrop should be accessible at: +If the web browser is running on **the same machine** as Docker, the Backdrop installation screen should be accessible at http://localhost:8088 -``` -http://{host-ip}:8080 -``` +### How to Access Backdrop in a Remote Docker Container -_(where `{host-ip}` is the IP address of the machine running docker)_ +If the web browser is running on **a different machine** than the one running docker, Backdrop should be accessible at http://{host-ip}:8088 (where `{host-ip}` is the IP address of the machine running Docker). +### Backdrop Installation - Database Credentials -# Backdrop Installation - Database Credentials Don't forget that the Backdrop install process requires the following database credentials to move onward: ``` @@ -114,73 +97,90 @@ Password: backdrop Database: backdrop ``` -# Validating Backdrop-Related Docker Containers +### Validating Backdrop-Related Docker Containers + Validating that Docker indeed constructed a valid runtime environment for Backdrop may be accomplished with the following command: ``` docker ps ``` -The resulting listing should include TWO (2) docker containers: +The resulting listing should include two Docker containers: - One for the MySQL database server that Backdrop requires (mysql) - One for Backdrop itself (backdrop) -``` -[example docker ps output here...] -``` +### How to Access the Backdrop host -## How to Access the Backdrop host Accessing the Backdrop host can be accomplished by issuing the following command on the machine running Docker: ``` docker exec -it backdrop bash ``` -## Trying Out the ALTERNATE Docker Images -The example `compose.yml` specifically references the `backdrop:latest` docker image. +This will result in creating a shell session _inside_ the container. To confirm this, try to browse the root of the filesystem and notice how it is different from your local root fileysytem: +``` +ls / +``` + +### Trying Out Other Docker Images -This is just in order to get people new to Docker started quickly and easily. Once someone becomes more familiar with Docker and using it to "spin up" containers, there is no reason why they wouldn't want to be curious about the **ALTERNATE** docker images, and wondering if one of those images suited their requirements better. +The example `compose.yml` above specifically references the `backdrop` Docker image. + +This is just in order to get people new to Docker quickly and easily started. Once someone becomes more familiar with Docker and how it is used to "spin up" the Backdrop application, there is no reason why they wouldn't want to try other Backdrop Docker images on Docker Hub or specific versions of the same image (using the [available tags](https://hub.docker.com/_/backdrop/tags)). To accomplish that, the only thing that needs be done is change the image specifier in the `backdrop` section of the `compose.yml` file. The general format to identify a specific Docker image is: ``` -repository:image +services: + backdrop: + image: {repository}/{image}:{tag} ``` +The image specifier is made up of 3 parts: a `{repository}`, `{image}` and `{tag}`. When `{repository}` is omitted, the format becomes `{image}:{tag}`. When the `{tag}` is omitted, this simply becomes `{image}`. -[Click here to see a complete list of every available Backdrop Official Docker Image](https://hub.docker.com/_/backdrop/tags) +> [!NOTE] +> The `{repository}` part above is omitted when the source of the image is [Docker Hub](https://hub.docker.com/). The `{tag}` is omitted when the tag desired is "latest". + +[Click here to see a list of available Backdrop Official-Docker-Image tags](https://hub.docker.com/_/backdrop/tags) # About Docker ![logo](https://raw.githubusercontent.com/docker-library/docs/c350af05d3fac7b5c3f6327ac82fe4d990d8729c/docker/logo.png) ## What is Docker? -Docker is an application that can significantly reduce the time, effort and cost involved when deploying software. It can dramatically reduce deployment time, often by an order of magnitude (hours to minutes, minutes to seconds). -Functionally speaking, Docker offers two main services: +Docker started off as a way to create "portable" linux applications, ones that can run on any OS as long as it has a Linux kernel. + +A good way to start to understand Docker is by learning about `chroot` and how it allowed us to fool the application we are running under Linux into thinking that the current folder holds the entirety of the root filesystem. Docker was born out of the desire to offer complete isolation for the running process from the current OS, not only in storage (as `chroot` accomplished), but also in device/process/user/network spaces. This involved leveraging other features of the Linux kernel similar to `chroot` to achive all of these types of isolation. Today, Docker offers a way to run processes along with their depedencies, all packaged together and while only requiring a Linux kernel. -- Docker provides a **build** environment that utilizes a Dockerfile to produce a Docker Image containing everything a target application might need to run. The short name for a Docker Image is simply "image". +_Functionally and practically speaking, Docker offers two main services:_ -- Docker provides a **run** environment wherein a Docker Image may be loaded and launched, thereby making the target application within that image accessible. The short name for the Docker Runtime Environment is "container". +- Docker provides a way to **build and run** portable applications. A Docker image is the portable application's executable and a Docker container is the portable application's running instance. These two concepts are simply referred to as _images_ and _containers_ in Docker. + +- Docker provides a way to **orchestrate** the building and running of multiple images/containers in tandem. This feature has been traditionally packaged as a separate tool called `docker-compose` but is now included with Docker itself, which is invoked using the subcommand `docker compose` and relies on the [Docker Compose file](https://github.com/compose-spec/compose-spec) syntax. ## What is a Dockerfile? -A Dockerfile is a human-redable script containing all the commands Docker needs to alter a source Docker Image into a target Docker Image. There is no short name for a Dockerfile, they are simply referred to as a "Dockerfile". + +A Dockerfile is a human-redable build script for building Docker images. The image is built using the `docker build` or `docker buildx build` commands. There is no short name for a Dockerfile, they are simply referred to as a "Dockerfile". ## What is a Docker Image? -A Docker Image ("image") is the result of a Docker build process. + +A Docker Image (or simply an "image") is the result of a Docker build process. It can be uploaded to Docker Hub or other registries and shared with others this way. ## What is a Backdrop Docker Official Image? -A Backdrop Docker Official Image is a Docker image that exposes the functionality of a Backdrop CMS instance in a container. These images have been prepared by the Backdrop CMS Project Team in order to spread awareness about Backdrop CMS and to help people quickly and easily deploy Backdrop CMS for evaluation purposes. +A Backdrop Docker Official Image is a Docker image that is understood to be issued and maintained by the people behind Backdrop iteself, rather than being developed by members of the community (since everyone can build and upload Docker images to Docker Hub). These images have been prepared by the Backdrop CMS Project Team in order to spread awareness about Backdrop CMS and to help people quickly and easily deploy Backdrop CMS for evaluation purposes. + +### What is a Default Docker Image? + +The default Docker image is the one that is installed by default by Docker when an incomplete image specifier is supplied (i.e. omitting the "tag" part). This capability was mostly developed for convenience, but it can also be thought of as a "catchall" or "fallback" strategy. This is usually the image with the tag "latest". -### What is a MAIN Docker Image? -The **MAIN** Docker image is the one that is installed by **DEFAULT** by Docker when an incomplete image specifier has been supplied. This capability was mostly developed for convenience, but it can also be thought of as a "catchall" or "fallback" strategy. It is also very useful when the latest version of an image is unknown as it will always install the preferred (and latest) version of an image unless instructed not to do so. +### What Other Docker Images are There? -### What is an ALTERNATE Docker Image? -**ALTERNATE** Docker images are a different story. These images must be fully specified if they are to be loaded and launched by Docker specifically _because_ they are not the prefered, latest image. Instead, they represent an exploration of "what if" scenarios with respect to Backdrop. Usually, this involves the incorporation of a different software sub-system, such as a different web server. Sometimes they represent a different version of the language that Backdrop was implemented in. Sometimes they represent a "snapshot" in the history of the development of Backdrop. In any event, accessing these images requires that they be fully and completely specified to Docker. +Alternative to the default Docker image, Backdrop and other projects may offer tagged images for specific versions, or alternative configurations (for example, Backdrop offers two varieties of images depending on the underlying web server). -[Click here to see a complete list of every available Backdrop Official Docker Image](https://hub.docker.com/_/backdrop/tags) +[Click here to see a complete list of available Backdrop Official Docker Image tags](https://hub.docker.com/_/backdrop/tags) # About Backdrop ![logo](https://backdropcms.org/files/inline-images/Backdrop-Logo-Horizontal_0.png) From ae8babb675451fdee6b564d76644b86e602cadcf Mon Sep 17 00:00:00 2001 From: Orwa Diraneyya <107997002+diraneyya@users.noreply.github.com> Date: Fri, 3 Jan 2025 17:03:12 +0100 Subject: [PATCH 5/5] Update README.md added a section on building own images --- README.md | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f3d8f5d..a96f817 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,25 @@ # Table of Contents -1. [Installation](#installation) +1. [Launch Backdrop using Docker](#launch-backdrop-using-docker) 2. [About Docker](#about-docker) 3. [About Backdrop](#about-backdrop) -# Installation -This document explains how to deploy Backdrop CMS as a Docker container application. +# Launch Backdrop using Docker + +> [!TIP] +> You **do not need** to clone this repository in order to launch Backdrop using Docker. + +This section explains how to launch Backdrop CMS as a Docker container application. The process of "spinning up" Backdrop as a Docker container application involves: 1) Ensuring Docker is installed on the host machine 2) Creating a named directory to hold Docker configuration file(s) - 3) Creating a new Docker startup file (also called: a _Docker Compose_ file) referencing a Backdrop Docker Image + 3) Creating a new Docker startup file (usually called: a _Docker Compose_ file) referencing a Backdrop Docker Image 4) Launching Docker in such a way that it processes the new Docker startup file (using the command `docker compose`) ## Step 1: Ensure Docker is Installed on the Host Machine + [Click here to see Docker's installation instructions for Windows, Mac and Linux](https://www.docker.com/get-started) The following example checks for the existence of Docker on a Linux host: @@ -34,6 +39,7 @@ cd backdrop-eval ``` ## Step 3: Create a New Docker Startup (i.e. _Docker compose_) File Referencing a Backdrop Docker Image + Docker offers a way to launch docker images that need to work together as an application. Such files are called _Docker compose_ files and are usually used when more than one Docker image is needed by the application. In the case of Backdrop, it is not sufficient to run the Backdrop Docker image which contains an Apache PHP application. Additionally, a MySQL database server is also needed. Hence, to "spin up" the Backdrop application (which involves running these two images), a Docker compose file is conveniently used. This is the `compose.yml` file, which contains all the settings needed to help Docker set up ad run the two containers, in a manner that allows them to interoperate as an application. @@ -137,12 +143,37 @@ services: image: {repository}/{image}:{tag} ``` -The image specifier is made up of 3 parts: a `{repository}`, `{image}` and `{tag}`. When `{repository}` is omitted, the format becomes `{image}:{tag}`. When the `{tag}` is omitted, this simply becomes `{image}`. +The image specifier is made up of the following parts: +| Part | Mandatory? | Default Value | Description | +|------|------------|---------------|-------------| +| `{repository}` | No | `docker.io` | is the URL at which a Docker image repository is serving a catalogue/collection of Docker images. When omitted, this defaults to [Docker Hub](https://hub.docker.com/). | +| `{image}` | Yes | - | is the name of the Docker image on the Docker repository. | +| `{tag}` | No | `latest` | is a variation of the image. When omitted, it defaults to "latest" (also called [the default image](#what-is-a-default-docker-image)). | > [!NOTE] -> The `{repository}` part above is omitted when the source of the image is [Docker Hub](https://hub.docker.com/). The `{tag}` is omitted when the tag desired is "latest". +> Depending on which parts are stated and which ones are omitted, you can encounter one of a few image specifier forms such as `{repository}/{image}`, `{image}:{tag}`, `{image}`, or `{repository}/{tag}`. -[Click here to see a list of available Backdrop Official-Docker-Image tags](https://hub.docker.com/_/backdrop/tags) +To view all the tags associated with the [official Backdrop image](#what-is-a-backdrop-docker-official-image) on Docker Hub, you can [click here](https://hub.docker.com/_/backdrop/tags). + +### Building and Using Your Modified Backdrop Docker Image + +Instead of using an image specifier in the `image` field in `compose.yml`. It is possible to point to a local directory containining a [Dockerfile](#what-is-a-dockerfile), as follows: + +``` +services: + backdrop: + image: + context: ./1/apache +``` + +In this case, the `docker compose` command would search the current folder (the folder in which the `compose.yml` file resides) for a subfolder named `1`, in which another subfolder `apache` exists, and look for a file called `Dockerfile` there (with a capitalized `D`). Inside of this file, are instructions on how to create a custom image using the [Dockerfile syntax](https://docs.docker.com/reference/dockerfile/). + +Example Dockerfiles for building Backdrop Docker images are found in this repository in the following locations: +- [/1/apache/Dockerfile](./1/apache/Dockerfile): is a Dockerfile that can be used to build a Docker image that uses Apache as an underlying server. +- [/1/fpm/Dockerfile](./1/fpm/Dockerfile): is a Dockerfile that can be used to build a Docker image that uses Nginx as an underlying server. + +> [!NOTE] +> Similar versions using either Apache or Nginx also exist on Docker Hub (using the `apache` and `fpm` tags, specifically), so unless the current images on Docker Hub are broken or that you want to modify these images, there won't usually be a need for you to build your own images as explained here. # About Docker