Skip to content

Commit

Permalink
Merge pull request #1 from adnnor/update-readme
Browse files Browse the repository at this point in the history 
Refine README.md for better and clear instructions
  • Loading branch information
@adnnor
adnnor authored Oct 25, 2024
2 parents 58aa409 + 49c4821 commit a5def90
Show file tree
Hide file tree
Showing 2 changed files with 216 additions and 110 deletions.
233 changes: 123 additions & 110 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected].

**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:

Expand All @@ -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
Expand All @@ -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 <service-name> 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 <container-id> [command]
# e.g.
docker exec -it <container-id> php -v"
docker exec -it <container-id> 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 <container-id> psql -U root -d dev
# or access the container
Expand All @@ -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 <container-id> psql -U root -d dev
```

For `.gz` archive:
```bash
# import a `.sql` file
cat path/to/your/file.sql | docker exec -i <container-id> psql -U root -d dev
# For `.gz` archive
gunzip < path/to/your/file.sql.gz | docker exec -i <container-id> psql -U root -d dev
```
### Export database dump
```bash
# export database
docker exec -t <container-id> pg_dump -U root -d dev > path/to/your/file.sql
```

## 4. pgAdmin
## pgadmin

Access pgAdmin at:
```
Expand All @@ -177,33 +189,33 @@ http://localhost:1435
- **Default Email:** `[email protected]`
- **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 <service_name>
## 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:

Expand All @@ -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/).

Loading

0 comments on commit a5def90

Please sign in to comment.