Skip to content

Install Guide

Jump to bottom
Sleeps edited this page Jul 2, 2026 · 1 revision

Things to know before diving in

  • This Web UI is a complete rewrite of the original 20 year old VEXIM2 web ui. There are a lot of changes and some of those are to the main VExim tables!
  • It no longer supports the siteadmin user login, you will need to create a new System Admin account via the CLI.
  • I have dropped support for Pipes, they are insecure
  • This has only been tested on Debian Bookworm (12) and Trixie (13).

Read the whole of this install guide before jumping in.

Things to do before you start

  • Backup your current VExim database. I cannot stress how important this is! Although I have tried to make everything reversible, it might not be and installing this makes changes to the core VExim tables.
  • Check your backup works..
  • Read the whole of this install guide.

Installing VExim Web UI

Make sure you have your current VExim database backed up, I know, I have said it before but it's pretty important.

Add a new veximweb system user account:

sudo adduser veximweb

You can change the account name but veximweb is what we will be using in this guide.

Then: su - veximweb and git clone https://github.com/MrSleeps/VExim-Web-UI.git

Now you need to rename the folder because capital letters in folder names are irritating.

mv VExim-Web-UI vexim_web

PHP

Now we need to make sure that you have PHP 8.4 or 8.5 installed (preferably 8.5):

sudo apt install -y php8.5 php8.5-bcmath php8.5-cli php8.5-curl php8.5-fpm php8.5-gd php8.5-imap php8.5-intl php8.5-ldap php8.5-mailparse php8.5-mbstring php8.5-mysql php8.5-soap php8.5-xml php8.5-zip

If that fails, install the Sury php repo and run that command again.

It is highly recommended that you run your own veximweb FPM server. To do that you can copy the config file found in docs/php/fpm/pool.d/ to your PHP FPM pool.d/ directory (on Debian it's located /etc/php/{VERSION}/fpm/pool.d/.

If you used "veximweb" as the new user account name you can copy the file straight over, if you changed the name you will need to edit the file and replace veximweb with whatever user account name you created.

Once that's done, you need to restart the FPM worker, if you are using 8.5 you can run:

service php8.5-fpm restart

If not, change the version number to whatever you are using.

Webserver

Time to configure your webserver, I use NGINX so there is a config file already ready for you in docs/nginx (called example.conf). You will need to update your PHP-FPM socket, the user (if you changed it from veximweb), the server name, ssl certs etc.

On Debian you might have to give the webserver permissions to access the veximweb accounts directories.

Once that's installed and you have restarted NGINX/Apache..

Setting up the web ui

su back into your veximweb account and cd into the vexim_web directory.

Copy the .env.example file to .env

cp .env.example .env

Crack open your favourite editor and edit the .env file

nano .env

You need to edit the following:

  • APP_URL
  • DB_CONNECTION
  • DB_HOST
  • DB_PORT
  • DB_DATABASE
  • DB_USERNAME
  • DB_PASSWORD
  • MAIL_HOST (Outgoing mail server so we can send emails)
  • MAIL_PORT
  • MAIL_USERNAME
  • MAIL_PASSWORD
  • MAIL_FROM_ADDRESS
  • MAIL_FROM_SUPPORT_ADDRESS
  • MAIL_FROM_SUPPORT_NAME
  • VEXIM_GID (GID of your VExim mail account)
  • VEXIM_UID (IID of your VExim mail account)
  • VEXIM_SYSADMIN_SET_GUID (not currently enabled but that's coming very soon)
  • VEXIM_SPAM_ENGINE
  • HEALTH_TO_ADDRESS (System does basic health checks, this is where you get the report emailed to)

You will also eventually need to edit

  • VEXIM_ENFORCE_2FA (Do not set this just yet, you need to setup 2FA before doing so) But don't do it just yet or you will lock yourself out of the web ui before starting.

The web ui needs access to your vexim database (or things are going to go very wrong in a minute).

Login to Mariadb/MySQL and create the user: CREATE USER 'newuser'@localhost IDENTIFIED BY 'strongpassword';

Grant permissions to the database (replace database_name to the one you are using for VExim2): GRANT ALL PRIVILEGES ON database_name.* TO 'newuser'@localhost WITH GRANT OPTION;

Apply the changes: FLUSH PRIVILEGES;

Now, tighten your belt.. It's about to get exciting.

But before we go any further, make sure YOU HAVE BACKED UP YOUR ORIGINAL VEXIM DATABASE.

Done that? Cool..

In the vexim_web directory run

./setup-web.sh

This little baby does most of the heavy lifting for you, it'll create the directories we need, it'll create any db tables we need, it creates a system account admin account for you.. You get the idea. It also allows you to install a fresh version of VExim (well, the tables at least). Don't answer yes to that question unless you are starting from a blank canvas.

Hopefully, that runs without any errors (make sure your database credentials are correct) and that is pretty much everything we need to do.

Now, you can login with the account you just created.. So hop on over to your newly installed VExim Web UI and marvel at bland colour scheme.

Clone this wiki locally