- 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
228 lines
6.1 KiB
Markdown
228 lines
6.1 KiB
Markdown
# 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_users2domains` table
|
|
- 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
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
### 2. Create Admin User
|
|
|
|
```bash
|
|
./build/imc --reset-admin-password
|
|
# This creates an admin user or resets the password
|
|
# Output: Username: admin, Password: (randomly generated)
|
|
```
|
|
|
|
### 3. Run
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./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 users
|
|
- `imc_login_attempts` - Brute force protection
|
|
- `imc_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](https://sqlc.dev/) for type-safe database access:
|
|
|
|
- SQL queries are defined in `backend/internal/db/queries/*.sql`
|
|
- Type-safe Go code is generated with `sqlc generate` into `backend/internal/db/sqlc/`
|
|
- **Do not edit files in `sqlc/`** - they are regenerated from queries
|
|
|
|
To regenerate after changing queries:
|
|
|
|
```bash
|
|
cd backend && sqlc generate
|
|
```
|
|
|
|
Enable SQL query logging in development:
|
|
|
|
```bash
|
|
USE_EMBEDDED=false ./build/imc
|
|
```
|
|
|
|
## Systemd Service
|
|
|
|
Example service file at `/etc/systemd/system/imc.service`:
|
|
|
|
```ini
|
|
[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](https://github.com/air-verse/air) for Go hot-reload: `go install github.com/air-verse/air@latest`
|
|
- [sqlc](https://sqlc.dev/) 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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
Build only frontend or backend:
|
|
|
|
```sh
|
|
make build-frontend
|
|
make build-backend
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|