Server Appearance Customization Guide (Custom HTML)

You can change the appearance of all web pages of your server without modifying the source code or recompiling.

Step 1 — Extract original files

First, extract the default files into a folder. Our recommended folder is /var/lib/maddy/www.

sudo maddy extract-www /var/lib/maddy/www

Step 2 — Set permissions

For the server to read the files, change folder ownership to the maddy user.

sudo chown -R maddy:maddy /var/lib/maddy/www

Step 3 — Enable in server

Update the server config file (maddy.conf) to use the new folder.

sudo sed -i '/chatmail.*{/a\    www_dir /var/lib/maddy/www' /etc/maddy/maddy.conf

Step 4 — Apply changes

Finally, restart the service for changes to take effect.

sudo systemctl restart maddy

Important: After performing the above steps, you can open files inside /var/lib/maddy/www with an editor (like nano) and modify them. Changes take effect immediately (after page refresh).

Note about Just-In-Time (JIT) registration

If you are customizing the main page (index.html), note that registration logic changes based on JIT status:

If JIT is enabled, user credentials are randomly generated in the browser.
If JIT is disabled (but registration is open), the browser uses the /new API to create accounts.

We recommend studying the JavaScript code for the generateAccount function in the default file.

Reset to default

If you want to use the program's built-in files again:

sudo sed -i '/www_dir/d' /etc/maddy/maddy.conf
sudo systemctl restart maddy