Add README.md

This commit is contained in:
Christoph Haas 2026-03-22 12:36:11 +01:00
parent 060f88dffe
commit 554b731ea8

154
README.md Normal file
View file

@ -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