malias-web/README.md

# Mailcow Alias Manager Web Interface..

A Python-based web application for managing mail aliases on a Mailcow instance. Built with Flask and a dark theme interface for internal network use. This application uses [malias](https://gitlab.pm/rune/malias) as base. Malias it self is a CLI application for managing aliases on a Mailcow Instance. If you already are using the CLI instance you can copy the the DB file over to your `/data` directory and you'll keep you API key etc. If you start with a blank DB you can use the `Sync Aliases` function to populate existing aliases to your local db.

## Features

- Dark-themed user interface
- Simple password authentication
- Manage Mailcow mail aliases through a web interface
- List all aliases on your Mailcow server (paginated view)
- Search for aliases in local database
- Create new permanent aliases
- Create time-limited aliases (1 year validity)
- Delete existing aliases
- Sync aliases from Mailcow server to local database
- View all mail domains

## Setup Instructions

### Option A: Docker (Recommended)

#### 1. Download the docker-compose.yml file

Download `docker-compose.yml` to your preferred directory.

#### 2. Start the application

```bash
docker compose up -d
```

The application will be available at: `http://localhost:5172`

#### 3. View logs (optional)

```bash
docker compose logs -f
```

#### 4. Stop the application (when needed)

```bash
docker compose down
```

### Option B: Manual Python Installation

#### 1. Create a virtual environment (recommended)

```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

#### 2. Install dependencies

```bash
pip install -r requirements.txt
```

#### 3. Run the application

```bash
python app.py
```

The application will be available at: `http://localhost:5172`

## Configuration

### 1. Configure Mailcow Connection

You can configure your Mailcow server connection either:

**Option A: Using the web interface (Recommended)**
- Click the "Configuration" button in the web interface
- Enter your Mailcow server (e.g., `mail.example.com` without https://)
- Enter your Mailcow API key
- Click Save

**Option B: Using malias.py directly**
```bash
python3 malias.py -s your.mailcow.server YOUR_API_KEY
```

### 2. Initial Sync

After configuring the connection, sync your aliases from the Mailcow server:
- Click the "Sync Aliases" button in the web interface
- This will populate the local database with your existing aliases

### 3. First Login

- Navigate to the login page
- Enter the default password: `admin123`
- You'll be redirected to the main application
- **IMPORTANT**: Immediately go to Configuration and change your password!

### 4. Change Default Password

After first login:
1. Click the "Configuration" button
2. Scroll to "Change Password" section
3. Enter current password: `admin123`
4. Enter your new password (minimum 6 characters)
5. Confirm your new password
6. Click "Change Password"

The password is stored encrypted in the database using bcrypt hashing.

## Usage

### Available Functions

**List All Aliases**
- Shows all aliases in a paginated table (20 per page)
- Navigate through pages using Previous/Next buttons

**Sync Aliases**
- Synchronizes aliases from Mailcow server to local database
- Run this periodically to keep local database up to date

**Show Domains**
- Lists all mail domains configured on your Mailcow instance

**Create Alias**
- Opens a dialog to create a new permanent alias
- Enter the alias email (e.g., `alias@example.com`)
- Enter the destination email where mail should be forwarded

**Delete Alias**
- Opens a dialog to delete an existing alias
- Enter the alias email to remove

**Create Timed Alias**
- Creates a time-limited alias (valid for 1 year)
- Enter the destination email (where the mail goes)
- Enter the domain to create the alias on
- The system will generate a unique timed alias

**Search Aliases**
- Search for aliases in the local database
- Searches both alias addresses and destination addresses
- Results show matching aliases with their destinations

**Configuration**
- Configure your Mailcow server address and API key
- Server address should be without `https://` (e.g., `mail.example.com`)
- Change your application password for security

## Mailcow API Integration

This application integrates with your existing `malias.py` script, which provides:
- Connection to Mailcow API
- Local SQLite database for caching aliases
- CRUD operations for mail aliases
- Time-limited alias creation
- Search and sync functionality

The web interface provides a user-friendly way to access these functions without using the command line.

## Security Note

This application uses password authentication with bcrypt hashing and is designed for internal network use. Security features:
- Passwords are hashed using bcrypt before storage
- Session-based authentication
- Password change functionality
- Minimum password length enforcement (6 characters)

For production use on a public network, consider implementing:
- HTTPS/TLS encryption
- More robust authentication mechanisms (2FA, OAuth, etc.)
- Rate limiting for login attempts
- Session timeout configuration
- Account lockout after failed attempts

Do not expose this application to the public internet without additional security measures, particularly HTTPS.

## Docker Details

The application runs in Docker with persistent data storage.

### Data Persistence

Your data is stored in the `./data` directory on your host machine:
- `malias2.db` - Database containing aliases and configuration
- `malias2.log` - Application logs

This directory persists across container restarts and updates.

### Customization

You can customize the timezone by editing `docker-compose.yml`:
```yaml
environment:
  - TZ=Europe/Oslo  # Change to your timezone
```

You can change the port by editing `docker-compose.yml`:
```yaml
ports:
  - "8080:5172"  # Change 8080 to your preferred port
```

### Useful Docker Commands

**View logs:**
```bash
docker compose logs -f
```

**Restart:**
```bash
docker compose restart
```

**Stop:**
```bash
docker compose down
```

**Update to newer version:**
```bash
docker compose pull
docker compose up -d
```

### Environment Variables:
You can customize the timezone in `docker-compose.yml`:
```yaml
environment:
  - TZ=Europe/Oslo  # Change to your timezone
```



### Docker Commands:

**Build and start (development):**
```bash
docker-compose up -d
```

**View logs:**
```bash
docker-compose logs -f mailcow-alias-manager
```

**Restart:**
```bash
docker-compose restart
```

**Stop:**
```bash
docker-compose down
```

**Rebuild after code changes:**
```bash
docker-compose up -d --build
```

## Documentation

- **README.md** - Main documentation (this file)
- **DOCKER.md** - Docker usage guide for end users

## What You Need

For Docker deployment:
- `docker-compose.yml` - The only file you need to download
- Docker and Docker Compose installed on your system

The application will automatically:
- Pull the Docker image
- Create the `data/` directory for your database
- Start on port 5172

For manual Python installation:
- All application files from the repository
- Python 3.11 or higher

## Troubleshooting

**"Error: No mailcow server or API key registered"**
- Make sure you've configured the Mailcow server and API key in the Configuration page
- The API key must have permissions to manage aliases on your Mailcow instance

**Search returns no results**
- Make sure you've run "Sync Aliases" first to populate the local database
- The search only searches the local database, not the live Mailcow server

**Connection errors**
- Verify your Mailcow server is accessible from the machine running this app
- Check that the API key is valid and has the correct permissions
- Review logs in `data/malias2.log`

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.