Skip to content

Commit 7b957ac

Browse files
dunaj-devdunaj-dev
committed
Add Docker Hub documentation and update README files
- Create README.dockerhub.md for Docker Hub description - Update README.md with Docker Hub image information - Reorganize README.docker.md to remove duplication - Add GitHub Actions workflow for updating Docker Hub description
1 parent e827d5e commit 7b957ac

File tree

4 files changed

+411
-240
lines changed

4 files changed

+411
-240
lines changed

‎.github/workflows/update-dockerhub.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Update Docker Hub Description
2+
3+
on:
4+
push:
5+
branches:
6+
- master # or main, depending on your default branch
7+
paths:
8+
- 'README.dockerhub.md'
9+
10+
jobs:
11+
update-dockerhub-description:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v2
15+
16+
- name: Update Docker Hub Description
17+
uses: peter-evans/dockerhub-description@v3
18+
with:
19+
username: ${{ secrets.DOCKERHUB_USERNAME }}
20+
password: ${{ secrets.DOCKERHUB_TOKEN }}
21+
repository: dunajdev/docker-mailserver-gui
22+
readme-filepath: ./README.dockerhub.md
23+
short-description: "Graphical user interface for managing Docker Mailserver"

‎README.docker.md‎

Lines changed: 178 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,178 @@
1-
# Docker Mailserver GUI - Docker Setup
2-
3-
This document provides instructions for deploying the Docker Mailserver GUI using Docker and Docker Compose.
4-
5-
## Prerequisites
6-
7-
- Docker Engine (version 19.03.0+)
8-
- Docker Compose (version 1.27.0+)
9-
- Running docker-mailserver container
10-
11-
## Directory Structure
12-
13-
```
14-
docker-mailserver-GUI/
15-
├── backend/ # Backend API
16-
├── frontend/ # Frontend React app
17-
├── docker/ # Docker configuration files
18-
│ ├── nginx.conf # Nginx configuration
19-
│ └── start.sh # Container startup script
20-
├── Dockerfile # Docker image configuration
21-
├── docker-compose.yml # Docker Compose configuration
22-
└── README.docker.md # Docker setup documentation
23-
```
24-
25-
## Configuration
26-
27-
Before running the application, you just need to adjust the `docker-compose.yml` file to match your docker-mailserver setup:
28-
29-
1. Update the `DOCKER_CONTAINER` environment variable to match your docker-mailserver container name
30-
31-
Example:
32-
```yaml
33-
environment:
34-
- DOCKER_CONTAINER=mail-server # Your docker-mailserver container name
35-
```
36-
37-
That's it! Since we're using Docker API via the socket, no network configuration is needed. The application will communicate with docker-mailserver through the Docker daemon on the host.
38-
39-
## Building and Running
40-
41-
To build and start the application:
42-
43-
```bash
44-
docker-compose up -d
45-
```
46-
47-
This will:
48-
1. Build the Docker image that includes both frontend and backend
49-
2. Start the container in detached mode
50-
3. Map port 80 for the web interface
51-
52-
## Accessing the Application
53-
54-
Once the container is running, you can access the web interface at:
55-
56-
```
57-
http://localhost
58-
```
59-
60-
## Stopping the Application
61-
62-
To stop the application:
63-
64-
```bash
65-
docker-compose down
66-
```
67-
68-
## Logs
69-
70-
To view logs from the container:
71-
72-
```bash
73-
docker-compose logs -f mailserver-gui
74-
```
75-
76-
## Updating
77-
78-
To update the application after making changes:
79-
80-
```bash
81-
docker-compose down
82-
docker-compose build
83-
docker-compose up -d
84-
```
85-
86-
## How It Works
87-
88-
The Docker setup uses a multi-stage build process:
89-
1. First stage builds the React frontend
90-
2. Second stage prepares the Node.js backend
91-
3. Final stage combines both into a single image with Nginx and Docker client
92-
93-
When the container starts:
94-
1. The backend Node.js server runs on port 3001 inside the container
95-
2. Nginx serves the frontend static files
96-
3. Nginx proxies API requests (/api/*) to the Node.js backend
97-
4. The backend communicates with your docker-mailserver container via Docker API
98-
99-
The application uses Docker API directly (via the dockerode library) to:
100-
1. Execute commands in the docker-mailserver container
101-
2. Check the container status and resource usage
102-
3. All operations are performed through the Docker socket (/var/run/docker.sock)
103-
104-
Unlike a traditional approach where containers need to be on the same network to communicate, using the Docker API through the socket means:
105-
1. The application talks to the Docker daemon on the host
106-
2. The Docker daemon then communicates with the docker-mailserver container
107-
3. No direct network connection between containers is needed
108-
4. This simplifies configuration and deployment
109-
110-
## Troubleshooting
111-
112-
### Connection to docker-mailserver fails
113-
114-
- Ensure the docker-mailserver container is running
115-
- Check that the container name matches the `DOCKER_CONTAINER` environment variable
116-
- Check that the `/var/run/docker.sock` volume is correctly mounted
117-
- Verify that your host user has permissions to access the Docker socket
118-
119-
### API errors
120-
121-
- Check the container logs: `docker-compose logs mailserver-gui`
122-
- Verify that the Nginx configuration correctly proxies to the backend
123-
- Ensure the backend can start properly
124-
125-
### Docker API connection issues
126-
127-
- Check that the Docker socket is correctly mounted in the container
128-
- Ensure your user has permissions to access the Docker socket
129-
- Verify that the Docker client is installed in the container
130-
131-
## Security Considerations
132-
133-
- The container has access to the Docker socket, which is a security risk. Make sure to restrict access to the container.
134-
- Consider setting up HTTPS for production deployments (you can modify the nginx.conf)
135-
- Add authentication to the web interface for production use
1+
# Docker Mailserver GUI - Detailed Docker Setup
2+
3+
This document provides detailed instructions for deploying and managing the Docker Mailserver GUI using Docker.
4+
5+
## Prerequisites
6+
7+
- Docker Engine (version 19.03.0+)
8+
- Running docker-mailserver container
9+
- Docker socket access (/var/run/docker.sock)
10+
- Docker Compose (version 1.27.0+ - only if using Option 2)
11+
12+
## Common Configuration
13+
14+
### Environment Variables
15+
16+
Both deployment options use the same environment variables:
17+
18+
- `DOCKER_CONTAINER`: The name of your docker-mailserver container (required)
19+
- `PORT`: Internal port for the Node.js server (defaults to 3001)
20+
- `NODE_ENV`: Node.js environment (defaults to production)
21+
22+
### Deployment Options
23+
24+
You can deploy Docker Mailserver GUI in two ways:
25+
26+
1. **Option 1: Using pre-built Docker Hub image** - Easiest method, no build required
27+
2. **Option 2: Building locally with Docker Compose** - For customization or development
28+
29+
Each option is detailed in the sections below.
30+
31+
## Project Structure
32+
33+
```
34+
docker-mailserver-GUI/
35+
├── backend/ # Backend API
36+
├── frontend/ # Frontend React app
37+
├── docker/ # Docker configuration files
38+
│ ├── nginx.conf # Nginx configuration
39+
│ └── start.sh # Container startup script
40+
├── Dockerfile # Docker image configuration
41+
├── docker-compose.yml # Docker Compose configuration
42+
└── README.docker.md # Docker setup documentation
43+
```
44+
45+
## Option 1: Using Docker Hub Image
46+
47+
The application is available as a pre-built Docker image on Docker Hub:
48+
49+
```bash
50+
docker run -d \
51+
--name mailserver-gui \
52+
-p 80:80 \
53+
-e DOCKER_CONTAINER=mailserver \
54+
-v /var/run/docker.sock:/var/run/docker.sock:ro \
55+
dunajdev/docker-mailserver-gui:latest
56+
```
57+
58+
Where:
59+
- `mailserver` is the name of your docker-mailserver container
60+
- Port 80 is mapped to your host
61+
62+
For more information about the Docker Hub image, visit:
63+
https://hub.docker.com/r/dunajdev/docker-mailserver-gui
64+
65+
## Option 2: Building Locally with Docker Compose
66+
67+
### Configuration
68+
69+
Before building the application, adjust the `docker-compose.yml` file to match your docker-mailserver setup:
70+
71+
1. Update the `DOCKER_CONTAINER` environment variable to match your docker-mailserver container name
72+
73+
Example:
74+
```yaml
75+
environment:
76+
- DOCKER_CONTAINER=mail-server # Your docker-mailserver container name
77+
```
78+
79+
That's it! Since we're using Docker API via the socket, no network configuration is needed. The application will communicate with docker-mailserver through the Docker daemon on the host.
80+
81+
### Building and Running
82+
83+
To build and start the application:
84+
85+
```bash
86+
docker-compose up -d
87+
```
88+
89+
This will:
90+
1. Build the Docker image that includes both frontend and backend
91+
2. Start the container in detached mode
92+
3. Map port 80 for the web interface
93+
94+
## Accessing the Application
95+
96+
Once the container is running, you can access the web interface at:
97+
98+
```
99+
http://localhost
100+
```
101+
102+
## Stopping the Application
103+
104+
To stop the application:
105+
106+
```bash
107+
docker-compose down
108+
```
109+
110+
## Logs
111+
112+
To view logs from the container:
113+
114+
```bash
115+
docker-compose logs -f mailserver-gui
116+
```
117+
118+
## Updating
119+
120+
To update the application after making changes:
121+
122+
```bash
123+
docker-compose down
124+
docker-compose build
125+
docker-compose up -d
126+
```
127+
128+
## How It Works
129+
130+
The Docker setup uses a multi-stage build process:
131+
1. First stage builds the React frontend
132+
2. Second stage prepares the Node.js backend
133+
3. Final stage combines both into a single image with Nginx and Docker client
134+
135+
When the container starts:
136+
1. The backend Node.js server runs on port 3001 inside the container
137+
2. Nginx serves the frontend static files
138+
3. Nginx proxies API requests (/api/*) to the Node.js backend
139+
4. The backend communicates with your docker-mailserver container via Docker API
140+
141+
The application uses Docker API directly (via the dockerode library) to:
142+
1. Execute commands in the docker-mailserver container
143+
2. Check the container status and resource usage
144+
3. All operations are performed through the Docker socket (/var/run/docker.sock)
145+
146+
Unlike a traditional approach where containers need to be on the same network to communicate, using the Docker API through the socket means:
147+
1. The application talks to the Docker daemon on the host
148+
2. The Docker daemon then communicates with the docker-mailserver container
149+
3. No direct network connection between containers is needed
150+
4. This simplifies configuration and deployment
151+
152+
## Troubleshooting
153+
154+
### Connection to docker-mailserver fails
155+
156+
- Ensure the docker-mailserver container is running
157+
- Check that the container name matches the `DOCKER_CONTAINER` environment variable
158+
- Check that the `/var/run/docker.sock` volume is correctly mounted
159+
- Verify that your host user has permissions to access the Docker socket
160+
161+
### API errors
162+
163+
- Check the container logs: `docker-compose logs mailserver-gui`
164+
- Verify that the Nginx configuration correctly proxies to the backend
165+
- Ensure the backend can start properly
166+
167+
### Docker API connection issues
168+
169+
- Check that the Docker socket is correctly mounted in the container
170+
- Ensure your user has permissions to access the Docker socket
171+
- Verify that the Docker client is installed in the container
172+
173+
## Security Considerations
174+
175+
- The container has access to the Docker socket, which is a security risk. Make sure to restrict access to the container.
176+
- Consider setting up HTTPS for production deployments (you can modify the nginx.conf)
177+
- Add authentication to the web interface for production use
178+

0 commit comments

Comments
 (0)