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`