Skip to content

geniusdynamics/ns8-postal

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Postal for NethServer 8

Postal Logo

License: GPL v3 GitHub Actions NethServer 8

πŸ“§ Overview

Postal is a complete and fully featured mail server for use by websites & web servers. Think Sendgrid, Mailgun or Postmark but open source and ready for you to run on your own servers.

This module provides seamless integration of Postal with NethServer 8, offering:

  • πŸš€ Full-featured mail server - Send, receive, and manage emails
  • πŸ”’ Built-in security - DKIM, SPF, and bounce handling
  • πŸ“Š Comprehensive analytics - Track deliveries, opens, and clicks
  • 🌐 Web-based interface - Modern UI for mail management
  • πŸ”§ API access - RESTful API for integration
  • πŸ“ˆ High performance - Built for scale and reliability

πŸš€ Quick Start

Installation

Install the Postal module on your NethServer 8 instance:

add-module ghcr.io/geniusdynamics/postal:latest 1

Example output:

{
  "module_id": "postal1", 
  "image_name": "postal", 
  "image_url": "ghcr.io/geniusdynamics/postal:latest"
}

Configuration

Configure your Postal instance (assuming instance name is postal1):

api-cli run configure-module --agent module/postal1 --data - <<EOF
{
  "host": "mail.yourdomain.com",
  "http2https": true,
  "lets_encrypt": true
}
EOF

Configuration Parameters

Parameter Type Required Description
host string βœ… Fully qualified domain name (e.g., mail.example.com)
http2https boolean βœ… Force HTTPS redirection
lets_encrypt boolean βœ… Enable Let's Encrypt SSL certificate

Access Your Mail Server

After configuration, Postal will be available at:

  • Web Interface: https://your-configured-host
  • SMTP: Port 2525
  • IMAP: Port 2143

πŸ”§ Management Commands

Get Current Configuration

api-cli run get-configuration --agent module/postal1

Update Module

api-cli run update-module --data '{
  "module_url": "ghcr.io/geniusdynamics/postal:latest",
  "instances": ["postal1"],
  "force": true
}'

Uninstall

remove-module --no-preserve postal1

πŸ—οΈ Architecture

Services

The module deploys the following containerized services:

  • postal-app: Main Postal application server
  • postal-smtp-app: SMTP service for sending emails
  • postal-worker-app: Background worker for processing tasks
  • mariadb-app: Database backend
  • caddy-app: Web server and reverse proxy

Network Configuration

  • Port 5000: Internal web interface (proxied through Traefik)
  • Port 2525: SMTP service
  • Port 2143: IMAP service

Data Persistence

Persistent data is stored in:

  • Database files and configurations
  • Mail queues and logs
  • SSL certificates (if Let's Encrypt is enabled)

πŸ” Advanced Configuration

Smarthost Integration

Postal automatically integrates with NethServer 8's smarthost configuration:

  • Configuration is discovered from Redis keys
  • The bin/discover-smarthost script refreshes settings on startup
  • Changes are automatically applied via event handlers

Custom Configuration Files

Key configuration templates:

  • imageroot/templates/postal.yml.j2 - Main Postal configuration
  • imageroot/templates/Caddyfile.j2 - Web server configuration

πŸ› οΈ Development & Debugging

Debug Commands

  1. Check general environment state:

    runagent -m env
  2. Check instance environment variables:

    runagent -m postal1 env
  3. Enter agent environment:

    runagent -m postal1
  4. View running containers:

    runagent -m postal1
    podman ps
  5. Access container shell:

    runagent -m postal1 podman exec -it postal-app /bin/bash

    Inside the container, you can run:

    • Initialize Postal:
      postal initialize
    • Create a new user:
      postal make-user
    • View configuration:
      cat config/postal.yml
  6. Inspect container environment:

    podman exec postal-app env
  7. Access container shell in sh:

    podman exec -ti postal-app sh

    Check specific configurations with:

    cat config/postal.yml

    These commands are essential for debugging and managing the Postal instance effectively.

Project Structure

ns8-postal/
β”œβ”€β”€ imageroot/                 # Module runtime files
β”‚   β”œβ”€β”€ actions/              # Module actions (configure, restore, etc.)
β”‚   β”œβ”€β”€ bin/                  # Utility scripts
β”‚   β”œβ”€β”€ events/               # Event handlers
β”‚   β”œβ”€β”€ systemd/              # Systemd service definitions
β”‚   └── templates/            # Configuration templates
β”œβ”€β”€ ui/                       # Web interface
β”‚   β”œβ”€β”€ src/                  # Vue.js application source
β”‚   └── public/               # Static assets and metadata
β”œβ”€β”€ tests/                    # Automated tests
└── build-images.sh          # Image building script

πŸ§ͺ Testing

Run the automated test suite:

./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/postal:latest

Tests are implemented using Robot Framework and cover:

  • Module installation and configuration
  • Service health checks
  • Basic functionality validation

Manual Testing

  1. Verify services are running:

    runagent -m postal1
    systemctl --user status postal.service
  2. Check logs:

    podman logs postal-app

🌍 Internationalization

The module supports multiple languages through Weblate.

Supported Languages:

  • English (en)
  • German (de)
  • Spanish (es)
  • Italian (it)
  • Portuguese (pt, pt_BR)
  • Basque (eu)

Contributing Translations:

  1. Join the NethServer Weblate project
  2. Add translations for the postal component
  3. Submit pull requests for new language files

πŸ“š Documentation

🀝 Contributing

We welcome contributions! Please see our contribution guidelines for details.

Development Setup

  1. Clone the repository:

    git clone https://github.com/geniusdynamics/ns8-postal.git
    cd ns8-postal
  2. Build development images:

    ./build-images.sh
  3. Run tests:

    ./test-module.sh localhost:9999 postal:latest

πŸ“ž Support

πŸ“„ License

This project is licensed under the GNU General Public License v3.0.

Copyright (C) 2023 Genius Dynamics

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

πŸ‘₯ Authors


Made with ❀️ by the Genius Dynamics team
Powered by NethServer 8

About

Postal Server App for nethserver 8

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors 2

  •  
  •