From 49c4821a6fde6dc179ea27c6fb1e4065cd1bb6e8 Mon Sep 17 00:00:00 2001 From: Adnan Shahzad Date: Fri, 25 Oct 2024 19:38:33 +0500 Subject: [PATCH] Refine README.md for better and clear instructions --- README.md | 233 +++++++++++++++++++++++++---------------------- docker-cheats.md | 93 +++++++++++++++++++ 2 files changed, 216 insertions(+), 110 deletions(-) create mode 100644 docker-cheats.md diff --git a/README.md b/README.md index 296d61b..17221a4 100644 --- a/README.md +++ b/README.md @@ -2,44 +2,106 @@ This guide provides an overview of managing your docker setup that includes PHP, Nginx, OpenSearch, PostgreSQL, pgAdmin, Redis, Supervisor and MailCatcher. You will learn how to start and stop containers, access specific services, check the database and email systems, and more. -Feel free to update this README.md if you notice anything missing. If you need a different version of Nginx or PHP, please reach out to adnnor@gmail.com. -**Credits** -Some parts of this setup, especially the Elasticsearch configuration and the concepts of file management and mounts, are adapted from [Markshust's Docker Setup for Magento](https://github.com/markshust/docker-magento). +## Table of Contents +- [File Structure](#file-structure) + - [env](#env) + - [src](#src) + - [conf](#conf) + - [docker-compose.yml](#docker-composeyml) +- [Services](#services) + - [app](#app) + - [phpfpm](#phpfpm) + - [supervisor](#supervisor) + - [postgres](#postgres) + - [pgadmin](#pgadmin) + - [rabbitmq](#rabbitmq) + - [mailcatcher](#mailcatcher) +- [Credits](#credits) +- [Extras](#extras) + +Please feel free to update this README.md if you notice anything that is missing. If you need a different version of Nginx or PHP, kindly fill out the form at [this link](https://docs.google.com/forms/d/1PA9piAEZfOT3rp3SQqsq8ASz2dIYLldU8lQQ-fPzvlQ/prefill). + +## File Structure + +This section outlines the key directories and files in the project, including configuration files, environment variable files, and application source code. Understanding the structure will help you manage the setup, configuration, and operation of the Docker-based environment effectively. + + +#### env +Contains environment variable files for different services. + +- `phpfpm.env`: Environment variables for the PHP-FPM service. +- `postgres.env`: Environment variables for the PostgreSQL service. +- `pgadmin.env`: Environment variables for pgAdmin. +- `elasticsearch.env`: Environment variables for Elasticsearch. +- `rabbitmq.env`: Environment variables for RabbitMQ. + +#### conf +Contains configuration files for various services. + +- `nginx.default.conf`: Nginx configuration file. +- `.env-app.local`: Environment file for Oro Commerce. +- `supervisord.conf`: Supervisor configuration to manage background processes. + +#### src +The base directory where the application source code is located. Mounted to `/var/www/html` within containers. + +## docker-compose.yml +Defines services, volumes, networks, and mounts used in the Docker setup. + +Check the complete [Docker Cheat Sheet](./docker-cheat-sheet.md) for useful Docker commands. + +#### Volumes +Volumes are used to persist data across container restarts: + +- `postgres-data`: Stores PostgreSQL data. +- `pgadmin-data`: Stores pgAdmin data. +- `rabbitmqdata`: Stores RabbitMQ data. +- `sockdata`: Socket files for Nginx communication. + +#### Networks +The `oro` network is defined as a `bridge` network, enabling inter-service communication. + +#### Mounts +The following directories and files are mounted to the containers: + +The **Oro code base** is mounted from `./src:/var/www/html:cached`. This ensures that the application source code on your local machine is synchronized with the container, allowing for smooth development and real-time updates. + +The **nginx configuration** is copied from `./conf/nginx.default.conf:/etc/nginx/conf.d/default.conf:cached`. This sets up the server configuration inside the container using your local Nginx configuration file. + +The **environment file for Oro** is mounted from `./conf/.env-app.local:/var/www/html/.env-app.local:cached`. This file provides the necessary environment variables for the Oro application to run properly. + +Your **Composer configuration** is mounted from `~/.composer:/var/www/.composer:cached`. This allows the container to use your local Composer settings, enabling seamless dependency management for PHP projects. + +Your **SSH keys** are mounted from `~/.ssh:/var/www/.ssh:cached`. This ensures the container has access to your SSH keys, which is useful for secure access to private repositories or servers. -## The phpfpm service -Common PHP extensions: `bcmath`, `bz2`, `calendar`, `exif`, `ftp`, `gd`, `gettext`, `intl`, `mbstring`, `mysqli`, `opcache`, `pcntl`, `pdo_mysql`, `soap`, `sockets`, `sodium`, `sysvmsg`, `sysvsem`, `sysvshm`, `xsl`, `zip` -Redis -Imagick -SSH2 -Swoole -Blackfire -Node.js v20.x -Composer v2.6.6 -Git v2.x -Redis CLI -Xdebug v3.3.2 -nano and vi ;-) - -## The app service +Finally, the **known hosts file** is mounted from `~/.ssh/known_hosts:/var/www/.ssh/known_hosts:cached`. This provides a list of SSH hosts your machine has connected to, ensuring smoother SSH operations within the container. + +## app Nginx is configured to serve PHP applications, utilizing FastCGI for processing PHP files. The service supports both HTTP and HTTPS traffic. 1. **User and Permissions** The Nginx service runs as a non-root user (`app`) for security. Ensure that the appropriate permissions are set on the mounted directories to avoid permission issues. -2. **Using with Magento** - If you are using this Nginx setup for Magento, uncomment the following line in your Docker Compose file to mount the sample Nginx configuration (only available in docker-compose.mysql-pms.yml): - ```yaml - #- ./src/nginx.conf.sample:/var/www/html/nginx.conf:cached - ``` - 3. **Volume Mounting** The volume `./src:/var/www/html:cached` is mounted, allowing your application files to be served from the `src` directory on your host machine. Ensure your application files are located in this directory for proper operation. 4. **Logs** Access and error logs are located at `/var/log/nginx/access.log` and `/var/log/nginx/error.log`, respectively. Monitor these logs for troubleshooting and performance analysis. -## The supervisor service +## phpfpm + +Installed PHP extensions are: `bcmath`, `bz2`, `calendar`, `exif`, `ftp`, `gd`, `gettext`, `intl`, `mbstring`, `mysqli`, `opcache`, `pcntl`, `pdo_mysql`, `soap`, `sockets`, `sodium`, `sysvmsg`, `sysvsem`, `sysvshm`, `xsl`, `zip` + +- Redis (redis-cli is available) +- Node.js v20.x +- Composer v2.6.6 +- Git v2.x +- Xdebug v3.3.2 +- nano and vi/vim! for sure ;) + + +## supervisor The required background processes are the following: @@ -59,35 +121,22 @@ The `supervisord.conf` file is already available under the `conf` directory. You ``` [Configure the Supervisor - Oro Documentation](https://doc.oroinc.com/backend/setup/installation/#configure-the-supervisor) -**Useful supervisord commands** -- `supervisorctl reread` - Reloads the configuration files. -- `supervisorctl update` - Updates Supervisor to include any new or modified programs. -- `supervisorctl status` - Checks the status of the running programs. +**Useful supervisor commands** +```bash +# reloads the configuration files +supervisorctl reread -## The rabbitmq service - -RabbitMQ is a message broker that facilitates communication between different components of the Oro application. It enables asynchronous processing of tasks, allowing for efficient handling of background jobs, notifications, and real-time messaging between services. - -**Ports** -- **Management UI:** Accessible at `http://localhost:15672` -- **Message Broker:** Uses port `5672` for communication. - -**Environment Configuration** -RabbitMQ environment variables are loaded from the `env/rabbitmq.env` file. You can customize settings like user credentials and other configurations here. Default credentials are `rabbit` for both username and password. - - - -#### Check the Status of the Background Processes - -To check the status of the background processes, run: +# update supervisor to include any new or modified programs +supervisorctl update -```bash +# check the status of the running programs supervisorctl status + ``` -You should see information similar to this: +Executing `supervisorctl status` should display information similar to this: ``` oro_message_consumer:oro_message_consumer_00 RUNNING pid 4847, uptime 0:05:36 @@ -98,44 +147,11 @@ oro_message_consumer:oro_message_consumer_04 RUNNING pid 4843, uptime 0:05:3 oro_web_socket RUNNING pid 5163, uptime 0:00:05 ``` -## 1. Starting and Stopping Containers - -**To start and stop the containers:** - -```bash -docker-compose -f docker-compose.yml up -d --remove-orphans # to start containers -docker-compose -f docker-compose.yml down # to down containers -``` -Note: The `--remove-orphans` option in the docker-compose up command is used to remove any containers that are not defined in the current docker-compose.yml file but were part of previous runs of Docker Compose. -## 2. Accessing Containers +## postgres +This section covers the PostgreSQL database activities. -To access any container, use the following command to get its name: -```bash -docker-compose ps -``` -Then, enter a container using: -```bash -docker-compose exec bash -# e.g -docker-compose exec phpfpm bash -``` - -You can also execute commands directly into the container without entering it by using: -```bash -docker ps # to get container ID - -docker exec -it [command] -# e.g. -docker exec -it php -v" -docker exec -it bin/console cache:clean --env=prod -``` - -## 3. PostgreSQL Database -This section covers the interaction with the database. -### Checking database service - -To check if the PostgreSQL database is running, log into the database: +To check if the database is running, log into the database: ```bash docker exec -it psql -U root -d dev # or access the container @@ -150,23 +166,19 @@ psql -U root -d dev - **Host:** `postgres` - **Default Database:** `dev` -### Importing database dump +**Importing database dump** -To import a `.sql` file: -```bash -cat path/to/your/file.sql | docker exec -i psql -U root -d dev -``` -For `.gz` archive: ```bash +# import a `.sql` file +cat path/to/your/file.sql | docker exec -i psql -U root -d dev +# For `.gz` archive gunzip < path/to/your/file.sql.gz | docker exec -i psql -U root -d dev -``` -### Export database dump -```bash +# export database docker exec -t pg_dump -U root -d dev > path/to/your/file.sql ``` -## 4. pgAdmin +## pgadmin Access pgAdmin at: ``` @@ -177,33 +189,33 @@ http://localhost:1435 - **Default Email:** `root@adnanshahzad.me` - **Password:** `root` -## 5. Checking Emails Using MailCatcher +You'll need to create a new server in pgAdmin to access the database. For database details, please refer to the [postgres](#postgres) section. -To check emails using MailCatcher, open your web browser and navigate to: -``` -http://localhost:1080 -``` -## 6. Checking ElasticSearch Health +## rabbitmq +RabbitMQ is a message broker that facilitates communication between different components of the Oro application. It enables asynchronous processing of tasks, allowing for efficient handling of background jobs, notifications, and real-time messaging between services. -```bash -curl -X GET "http://localhost:9200/_cluster/health" -``` +**Ports** +- **Management UI:** Accessible at `http://localhost:15672` +- **Message Broker:** Uses port `5672` for communication. +**Environment Configuration** +RabbitMQ environment variables are loaded from the `env/rabbitmq.env` file. You can customize settings like user credentials and other configurations here. Default credentials are `rabbit` for both username and password. -## 7. Checking Logs -To view logs for a specific service, use: -```bash -docker-compose logs +## mailcatcher + +To check emails using MailCatcher, open your web browser and navigate to: ``` -If you want to see logs for all services, simply run: -```bash -docker-compose logs +http://localhost:1080 ``` -## 8. Additional Information +## Credits + +Some parts of this setup, especially the Elasticsearch configuration and the concepts of file management and mounts, are adapted from [Markshust's Docker Setup for Magento](https://github.com/markshust/docker-magento). + +## Extras Other versions of PHP, Nginx, and Elasticsearch are available on Docker Hub under the `adnnor` repository, but only the following have been tested: @@ -216,3 +228,4 @@ Other versions of PHP, Nginx, and Elasticsearch are available on Docker Hub unde - `adnnor/elasticsearch:8.4` For installation, please refer to the official Oro Commerce documentation [here](https://doc.oroinc.com/backend/setup/installation/). + diff --git a/docker-cheats.md b/docker-cheats.md new file mode 100644 index 0000000..13190d9 --- /dev/null +++ b/docker-cheats.md @@ -0,0 +1,93 @@ +# Docker Cheat Sheet + +This file serves as a quick reference for useful Docker commands, helping you manage containers, volumes, and networks efficiently. It covers common tasks like starting and stopping containers, accessing running containers, managing Docker volumes and networks, and more. Whether you're troubleshooting or performing routine tasks, this cheat sheet provides the essential commands to streamline your Docker workflow. + +## Table of Contents +- [Containers](#containers) +- [Volumes](#volumes) +- [Networks](#networks) + +Please feel free to update this README.md if you notice anything that is missing. If you need a different version of Nginx or PHP, kindly fill out the form at [this link](https://docs.google.com/forms/d/1PA9piAEZfOT3rp3SQqsq8ASz2dIYLldU8lQQ-fPzvlQ/prefill). + +## Containers + +Start and stop the containers +```bash +docker-compose up -d --remove-orphans # to start containers +docker-compose down # to down containers +# use -f .yml if file name is other than docker-compose.yml, e.g. +docker-compose -f dev-compose.yml up -d +``` + +Note: The `--remove-orphans` option in the docker-compose up command is used to remove any containers that are not defined in the current docker-compose.yml file but were part of previous runs of Docker Compose. + + +Open a terminal inside container +```bash +docker-compose exec bash +# e.g +docker-compose exec phpfpm bash +``` + +Execute commands directly into the container without entering it by using: +```bash +# to get container ID or image name +docker ps +# then +docker exec -it [command] +# e.g. +docker exec -it php -v +docker exec -it bin/console cache:clean --env=prod +``` + +## Volumes +```bash +# to remove all volumes associated with the current docker-compose.yml +docker-compose down -v +# inspect a specific volume for details +docker volume inspect my-volume +# or to remove a specific volume +docker volume ls +# then copy the Volume Name, e.g., oro-docker_dbdata +docker volume rm oro-docker_dbdata +# get detailed usage information about volumes +docker system df -v +# remove all unused volumes +docker volume prune +``` + +## Networks +```bash +# list all docker networks +docker network ls + +# create a new bridge network +docker network create oro_local + +# inspect a specific network for details +docker network inspect oro + +# connect a running container to a network (use service name for docker-compose or container ID from docker ps) +docker network connect oro phpfpm + +# disconnect a container from a network (use service name for docker-compose or container ID from docker ps) +docker network disconnect oro phpfpm + +# remove a network (only if no containers are connected) +docker network rm oro + +# remove all unused networks +docker network prune + +``` + +## 7. Checking Logs + +To view logs for a specific service, use: +```bash +docker-compose logs +``` +If you want to see logs for all services, simply run: +```bash +docker-compose logs +```