- Document tool requirements (air, sqlc) with install commands - Explain that 'make dev' starts both servers - Clarify which port to use (5173 for frontend dev, 8080 for backend) - Document separate server commands - Consolidate requirements sections |
||
|---|---|---|
| backend | ||
| frontend | ||
| .env.example | ||
| .gitignore | ||
| Makefile | ||
| README.md | ||
IMC
A self-sufficient web application to manage an ISPmail (Postfix, Dovecot, Rspamd) mail server.
Features
- Domain Management - Add, view, and delete mail domains
- User Management - Create and manage mail users per domain
- Alias Management - Create and manage email aliases per domain
- Mail Queue - View, requeue, and delete queued emails
- Mail Logs - View postfix logs with filtering
- Password Management - Change password for admin users
Tech Stack
- Backend: Go with Gin framework, sqlc for type-safe SQL
- Frontend: SvelteKit
- Database: MariaDB/MySQL (shared with mail server ISPmail schema)
- Auth: JWT-based authentication
Architecture
- Single binary with embedded frontend (no separate web server needed)
- All database tables use
imc_prefix to avoid conflicts with ISPmail schema - Permissions controlled via
imc_users2domainstable - Admin users have access to all domains; non-admin users only to assigned domains
Directory Structure
imc-vibe/
├── backend/ # Go backend
│ ├── cmd/server/ # Application entry point
│ │ ├── main.go # Main function, CLI flags, HTTP server setup
│ │ ├── frontend.go # Embedding the SvelteKit build
│ │ └── embed/ # Embedded frontend files (generated)
│ └── internal/ # Internal packages
│ ├── api/ # HTTP API routing and handlers
│ │ ├── router.go # Gin route definitions
│ │ └── handlers/ # HTTP handlers
│ ├── auth/ # JWT authentication
│ ├── config/ # Configuration loading
│ ├── db/ # Database access layer
│ │ ├── queries/ # SQL query files (sqlc source)
│ │ └── sqlc/ # Generated type-safe Go code
│ └── mail/ # Mail server integration (postqueue, logs, quota)
├── frontend/ # SvelteKit frontend
│ ├── src/
│ │ ├── app.css # Global CSS (Tailwind + daisyUI)
│ │ ├── app.html # HTML template
│ │ ├── lib/ # Shared utilities
│ │ └── routes/ # SvelteKit routes (pages)
│ ├── vite.config.ts # Vite configuration
│ └── package.json # Frontend dependencies
├── build/ # Built binary output (gitignored)
├── Makefile # Build automation
└── .env # Environment configuration (gitignored)
Quick Start
1. Build
make build
2. Create Admin User
./build/imc --reset-admin-password
# This creates an admin user or resets the password
# Output: Username: admin, Password: (randomly generated)
3. Run
./build/imc --bind=0.0.0.0 --port=8080
4. Access
Open http://your-server:8080 and login with the admin credentials.
Configuration
Environment Variables
| Variable | Description | Default |
|---|---|---|
DB_HOST |
Database host | localhost |
DB_PORT |
Database port | 3306 |
DB_USER |
Database user | mailadmin |
DB_PASSWORD |
Database password | (required) |
DB_NAME |
Database name | mailserver |
BIND |
IP to bind to | 0.0.0.0 |
PORT |
Port to listen on | 8080 |
JWT_SECRET |
JWT signing secret (min 32 chars) | (required) |
CLI Flags
./imc --help
-bind string
IP address to bind to (default: 0.0.0.0)
-port string
Port to listen on (default: 8080)
-reset-admin-password
Reset admin password to a random value and exit
Database Tables
The app creates these tables automatically:
imc_users- App admin usersimc_login_attempts- Brute force protectionimc_users2domains- User-domain permissions
Existing ISPmail tables (virtual_domains, virtual_users, virtual_aliases) are used for mail data.
Database Access with sqlc
The app uses sqlc for type-safe database access:
- SQL queries are defined in
backend/internal/db/queries/*.sql - Type-safe Go code is generated with
sqlc generateintobackend/internal/db/sqlc/ - Do not edit files in
sqlc/- they are regenerated from queries
To regenerate after changing queries:
cd backend && sqlc generate
Enable SQL query logging in development:
USE_EMBEDDED=false ./build/imc
Systemd Service
Example service file at /etc/systemd/system/imc.service:
[Unit]
Description=IMC Mail Admin
After=network.target mariadb.service postfix.service
[Service]
Type=simple
User=root
Environment=DB_HOST=localhost
Environment=DB_PORT=3306
Environment=DB_USER=mailadmin
Environment=DB_PASSWORD=your_password
Environment=DB_NAME=mailserver
Environment=JWT_SECRET=your_secret
Environment=BIND=0.0.0.0
Environment=PORT=8080
ExecStart=/opt/imc/imc
[Install]
WantedBy=multi-user.target
Requirements
- Go 1.21+
- Bun (for frontend development)
- MariaDB/MySQL
- Postfix (with postqueue/postsuper)
- systemd-journald (for log viewing)
Development
Tool Requirements
- air for Go hot-reload:
go install github.com/air-verse/air@latest - sqlc for SQL code generation:
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
Running Development Server
Start both frontend and backend with hot-reload:
make dev
This starts:
- Frontend on http://localhost:5173 (SvelteKit with HMR - frontend changes auto-reload)
- Backend on http://localhost:8080 (Go API with hot-reload)
During development, access the app at http://localhost:5173 - the Vite dev server proxies /api requests to the backend and enables instant frontend updates.
Running Servers Separately
# Backend only (port 8080, serves frontend from frontend/build/)
make dev-backend
# Frontend only (port 5173)
make dev-frontend
Building
Build the binary into the build/ directory:
make build
Build only frontend or backend:
make build-frontend
make build-backend
License
MIT