Skip to content

Commit 74dd5c7

Browse files
dunaj-devdunaj-dev
committed
Initial commit
0 parents  commit 74dd5c7

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+10140
-0
lines changed

‎.github/workflows/docker-publish.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Build and Publish Docker Image
2+
3+
on:
4+
push:
5+
branches: [ "master" ]
6+
tags: [ 'v*.*.*' ]
7+
pull_request:
8+
branches: [ "master" ]
9+
10+
env:
11+
IMAGE_NAME: dunajdev/docker-mailserver-gui
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: read
18+
packages: write
19+
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Docker Buildx
25+
uses: docker/setup-buildx-action@v3
26+
27+
- name: Log in to Docker Hub
28+
if: github.event_name != 'pull_request'
29+
uses: docker/login-action@v3
30+
with:
31+
username: ${{ secrets.DOCKERHUB_USERNAME }}
32+
password: ${{ secrets.DOCKERHUB_TOKEN }}
33+
34+
- name: Extract metadata for Docker
35+
id: meta
36+
uses: docker/metadata-action@v5
37+
with:
38+
images: ${{ env.IMAGE_NAME }}
39+
tags: |
40+
type=ref,event=branch
41+
type=ref,event=pr
42+
type=semver,pattern={{version}}
43+
type=semver,pattern={{major}}.{{minor}}
44+
type=sha,format=short
45+
type=raw,value=latest,enable={{is_default_branch}}
46+
47+
- name: Build and push Docker image
48+
uses: docker/build-push-action@v5
49+
with:
50+
context: .
51+
push: ${{ github.event_name != 'pull_request' }}
52+
tags: ${{ steps.meta.outputs.tags }}
53+
labels: ${{ steps.meta.outputs.labels }}
54+
cache-from: type=gha
55+
cache-to: type=gha,mode=max

‎CLAUDE.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Docker Mailserver GUI Development Guidelines
2+
3+
## Project Overview
4+
- **Purpose:** GUI for managing Docker Mailserver (accounts, aliases, server status)
5+
- **Architecture:** Single Docker container with frontend and backend
6+
- **Technology Stack:** React frontend, Node.js/Express backend, Docker, Bootstrap
7+
8+
## Project Structure
9+
- **Backend:** Express API communicating with Docker Mailserver via Docker API
10+
- **Frontend:** React SPA with Bootstrap styling and i18n internationalization
11+
- **Components:** Reusable UI components in `frontend/src/components`
12+
- **Docker:** Single containerized application with Nginx and Node.js
13+
14+
## Project Commands
15+
- **Local Development:**
16+
- Backend: `cd backend && npm run dev` - Start backend with hot-reload
17+
- Frontend: `cd frontend && npm start` - Start frontend dev server
18+
- Build: `cd frontend && npm run build` - Build frontend for production
19+
- **Docker:**
20+
- Build and start: `docker-compose up -d`
21+
- Logs: `docker-compose logs -f mailserver-gui`
22+
- Rebuild: `docker-compose down && docker-compose build && docker-compose up -d`
23+
24+
## Code Style Guidelines
25+
- **Imports:** Group imports by type (React, libraries, components, CSS)
26+
- **Components:** Use functional components with React hooks
27+
- **Naming:** PascalCase for components, camelCase for functions/variables
28+
- **Code Structure:** Centralized API calls in services directory
29+
- **Error Handling:** Use translation keys for error messages (not pre-translated strings)
30+
- **Internationalization:** Use i18n translation keys for all user-facing text
31+
- **Formatting:** 2 spaces indentation
32+
- **Comments:** Use English for all comments
33+
34+
## UI Components
35+
The project uses reusable components from `frontend/src/components`:
36+
- **AlertMessage:** For error and success notifications
37+
- **Button:** Standardized button component
38+
- **Card:** Container with optional header
39+
- **DashboardCard:** Special card for dashboard metrics
40+
- **DataTable:** For tabular data display
41+
- **FormField:** Text input field with validation
42+
- **SelectField:** Dropdown select with validation
43+
- **LoadingSpinner:** Loading indicator
44+
- **Navbar & Sidebar:** Navigation components
45+
- **LanguageSwitcher:** Language selector component
46+
47+
## Docker Implementation
48+
- Single container with both frontend and backend
49+
- Communication with docker-mailserver via Docker API (dockerode)
50+
- Requires only Docker socket mount (`/var/run/docker.sock`)
51+
- No direct network connection needed with docker-mailserver
52+
- Nginx serves static frontend and proxies API requests to backend
53+
54+
## Backend API with Docker
55+
The backend uses Docker API to:
56+
- Execute commands in the docker-mailserver container
57+
- Retrieve container status and statistics
58+
- Manage email accounts and aliases
59+
60+
## Best Practices
61+
- Maintain consistent error handling with translation keys
62+
- Use reusable components for UI elements
63+
- Handle loading/error states for all API requests
64+
- Follow RESTful patterns for API endpoints
65+
- Implement proper form validation

‎Dockerfile‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Multi-stage build for Docker Mailserver GUI
2+
# Stage 1: Build frontend
3+
FROM node:18-alpine as frontend-builder
4+
5+
WORKDIR /app/frontend
6+
7+
# Copy frontend package.json and install dependencies
8+
COPY frontend/package*.json ./
9+
RUN npm ci
10+
11+
# Copy frontend code and build
12+
COPY frontend/ ./
13+
RUN npm run build
14+
15+
# Stage 2: Build backend
16+
FROM node:18-alpine as backend-builder
17+
18+
WORKDIR /app/backend
19+
20+
# Copy backend package.json and install dependencies
21+
COPY backend/package*.json ./
22+
RUN npm ci --only=production
23+
24+
# Copy backend code
25+
COPY backend/ ./
26+
27+
# Install Docker client inside the container for Docker API access
28+
RUN apk add --no-cache docker-cli
29+
30+
# Stage 3: Final image with Nginx and Node.js
31+
FROM node:18-alpine
32+
33+
# Install Nginx and Docker client
34+
RUN apk add --no-cache nginx docker-cli
35+
36+
# Create app directories
37+
WORKDIR /app
38+
RUN mkdir -p /app/backend /app/frontend /run/nginx
39+
40+
# Copy backend from backend-builder
41+
COPY --from=backend-builder /app/backend /app/backend
42+
43+
# Copy frontend build from frontend-builder
44+
COPY --from=frontend-builder /app/frontend/dist /app/frontend
45+
46+
# Copy Nginx configuration
47+
COPY docker/nginx.conf /etc/nginx/http.d/default.conf
48+
49+
# Copy startup script
50+
COPY docker/start.sh /app/start.sh
51+
RUN chmod +x /app/start.sh
52+
53+
# Expose port for the application
54+
EXPOSE 80
55+
56+
# Start Nginx and Node.js
57+
CMD ["/app/start.sh"]

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Dunaj
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.docker.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
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

0 commit comments

Comments
 (0)