From 554b731ea84cf411d8d697cf031122b9dd9c34da Mon Sep 17 00:00:00 2001 From: Christoph Haas Date: Sun, 22 Mar 2026 12:36:11 +0100 Subject: [PATCH] Add README.md --- README.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e5b2c64 --- /dev/null +++ b/README.md @@ -0,0 +1,154 @@ +# IMC Vibe + +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 Reset** - SMTP-based password reset functionality + +## Tech Stack + +- **Backend**: Go with net/http (no framework), GORM for database +- **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 + +## Quick Start + +### 1. Build + +```bash +make build +``` + +### 2. Setup Admin User + +```bash +./build/imc-vibe --setup +# Or with custom credentials: +./build/imc-vibe --setup --admin-user=admin --admin-password=yourpassword +``` + +### 3. Run + +```bash +./build/imc-vibe --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 | (required) | +| `SMTP_HOST` | SMTP server for password reset | `localhost` | +| `SMTP_PORT` | SMTP port | `587` | +| `SMTP_USER` | SMTP username | | +| `SMTP_PASSWORD` | SMTP password | | +| `SMTP_FROM` | From address for emails | `noreply@localhost` | +| `BASE_URL` | Base URL for password reset links | `http://localhost:8080` | + +### CLI Flags + +```bash +./imc-vibe --help +``` + +``` + -admin-password string + Admin password for setup (required with --setup) + -admin-user string + Admin username for setup (default "admin") + -bind string + IP address to bind to (default: 0.0.0.0) + -port string + Port to listen on (default: 8080) + -setup + Create admin user 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 +- `imc_password_reset_tokens` - Password reset tokens + +Existing ISPmail tables (`virtual_domains`, `virtual_users`, `virtual_aliases`) are used for mail data. + +## Systemd Service + +Example service file at `/etc/systemd/system/imc-vibe.service`: + +```ini +[Unit] +Description=IMC Vibe 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-vibe/imc-vibe + +[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 + +```bash +# Build frontend and backend +make build + +# Run backend only (uses filesystem frontend) +cd backend && go run ./cmd/server + +# Run frontend dev server +cd frontend && bun run dev +``` + +## License + +MIT