No description
Find a file
Christoph Haas c83d8ee6da Update README with clear development setup documentation
- 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
2026-03-29 23:10:18 +02:00
backend Remove domains from auth API responses 2026-03-29 22:28:54 +02:00
frontend Fix 'make dev' to run both servers in parallel 2026-03-29 23:09:02 +02:00
.env.example Remove SMTP settings from .env.example 2026-03-26 00:25:08 +01:00
.gitignore Rename project from imc-vibe to imc 2026-03-24 23:42:37 +01:00
Makefile Fix 'make dev' to run both servers in parallel 2026-03-29 23:09:02 +02:00
README.md Update README with clear development setup documentation 2026-03-29 23:10:18 +02:00

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

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

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:

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