Install Zammad Helpdesk
When you run any type of support for any reason, the best tools you can have are a ticket (support request) tracking system and a knowledge base (KB). As an MSP or IT Services company, you'll be fielding support requests on a regular basis. You may even be creating the support actions yourself for your clients, and a great way to track your activities is using a system like Zammad. It allows you to document what you are doing, whether at the client's request, or as a proactive maintenance and security action you initiate. There are reporting tools that can then help you keep your client in the loop about what actions you are taking, and this tells them why their money is well spent on you andn your business.
the knowledge base is one of the most valuable items you'll have. It's a place to keep track of your processes and solutions for your internal teams, as well as a place to start working up documentation that can help your clients solve their own problems in many cases, and help keep your support staff open for those different and / or unique situations where the client really can't help themself.
Today, let's look at getting Zamma Helpdesk installed. It's a powerful helpdesk, knowledge base, and ticket tracking system. It's open source, and is incredibly powerful.
What you'll need:
- A host machine or server with at least 2 CPU cores available, adn 4 GB RAM available.
- Docker and Docker Compose installed on the machine.
- (optional, but recommended) a reverse proxy
- A domain or sub-domain you own that can be pointed to your host server's public IP address (alternatively you can setup a VPN to point to it, and use a public node as an ingress point to your private network).
- Email with the ability to setup and use different email addresses and SMTP support.
- About our time.
- git, wget, and curl installed on your server.
Email and Addresses
Before we get started on the install, I recommend setting up an email address you can login to the system with (this can just be your primary email address). For our install examples we'll use primary@myemail.org. You'll want a secondary email address as well, like no-reply@myemail.org, or support@my-email.org, and maybe both of those. You'll want to have the passwords for each of these handy, and they each need the ability to send and receive email (even if it says no-reply). Once you've set those up, make note of the SMTP settings for your email server / provider.
Installation via a Simple Script
You can easily install Docker-CE, Docker-Compose, Portainer-CE, and NGinX Proxy manager by using this quick install script I created and maintain on GitLab. Just use the command:
wget -O install-docker.sh https://gitlab.com/bmcgonag/docker_installs/-/raw/main/install_docker_nproxyman.sh
To download the script to your desired host.
Change the permissions to make the script executable:
chmod +x ./install-docker.sh
and then run the script with the command:
./install-docker.sh
When run, the script will prompt you to select your host operating system, then will ask you which bits of software you want to install.
Simply enter 'y' for each thing you want to install.
At some point, you may be asked for your super user (sudo) password as well.
Allow the script to complete installation.
At this point, you might want to log out and back in, as this will allow you to use the docker and docker compose commands without the need of sudo in front of them.
Prepare the System
For Zammad to run well, we need to set a system value to a higher max. In the terminal do the following command:
sysctl -w vm.max_map_count=262144
NOTE If you are setting this up in an LXC, LXD, or Incus Container, you may need to run this command on the host operating system instead.
Clone the Zammad Docker Compose repository with git. If you need to install git, wget, and curl, you can do it with these commands:
Debian / Ubuntu
sudo apt install git wget curl -y
Redhat, Centos, Fedora
sudo dnf install git wget curl -y
OpenSuse
sudo zypper install get wget curl -y
Arch
sudo pacman install get wget curl -y
Now use the command
git clone https://github.com/zammad/zammad-docker-compose.git
To pull down the Zammad docker compose repository to your server.
Move into the zammad-docker-compose directory with
cd zammad-docker-compose
Before we go too far, let's make a copy of our .env file. This is a hidden file in this directory, so you need to use
ls -al
to see it. We'll copy it with
cp .env .env.bak
This just makes sure we've got the original in case we mess anything up and need to start fresh. Now we'll edit the values in the .env file. There isn't a lot in here that we need to edit, but we do need to set a couple of items. We can open our text editor in the terminal using
nano .env
We need to edit the password that will be set for the database. This value is set to 'zammad' by default, and is not a secure password, so let's change that to something longer and stronger. You'll see it marked as the variable POSTGRES_PASS.
Once you've changed that to a nice long and stron gpassword, save your changes with CTRL + O, then press Enter to confirm, and exit the text editor with CTRL + X.
Next, let's look at our docker-compose.override.yml file. This file has a port mapping that you may need / want to change. Zammad by default used port 8080 as it's port for the web server. This is a very common port and is used by a lot of applications. If you are already using thisport on your host machine, it's important that you change this port in the override file now. If you need to change it follow these steps.
nano docker-compose.override.yml
move down to the port mapping line:
- "8080:8080"
and change the port on the left side of the colon only. For instance to set Zammad to run on port 8082, we would make this line look like:
- "8082:8080"
After you've made your change, save the file with CTRL + O, then press Enter to confirm, and exit the nano editor with CTRL + X.
Now we are ready to pull down the images for Zammad. We can do this at the same time as we start the containers, and we can even start watching the log output as the containers start with a one line combination of two commands:
docker compose up -d && docker compose logs -f
Once you start this running, you should see the images being pulled down, and once the containers are started, you'll start seeing a live stream of the log output as the system is being setup and started for the first time. Be patient. This process (especially the first time, can take from 5 to 15 minutes, maybe more depending on the hardware you are running on, as well as the bandwidth of your internet connection.
As long as you don't see any errors in the logs as they scream past, your system should come up and running in a few minutes. You can stop viewing the logs by pressing CTRL + C.
Test Our Site
To see if our site is working, open your favorite browser, and navigate to the IP address of your host server, and the port you set on the left side of the port mapping. I left it as 8080 since my server wasn't already using that port. So I went to:
You should go to the IP and port your host is using. You should see the Zammad logo, and eventually a button to start the setup wizard. We don't want to start the wizard quite yet though. We want to get our site setup to be accessed via the domain name, and we want it to be through https with a valid SSL certificate.
Setup The Reverse Proxy
I'll be using NGinX Proxy Manager, but feel free to use any reverse proxy you want. If you are running Zammad on a VPS or other machine that is directly connected to the internet with a public IP address, a reverse proxy may not be necessary for you. In my case I have my Zammad server inside a VPC (Virtual Private Cloud) with it's on internal LAN. So I'll use the LAN to setup the service on from my reverse proxy and then I can setup a firewall in front of it from the public internet.
If you aren't using NGinX Proxy manager, then feel free to skip this secton. Otherwise, in NPM (NGinX Proxy Manager), create a new Proxy host, and put in the domain / subdomain name of your Zammad install. I used "support.sysmainit.com". After you enter the somain /sub-domain anme, press the TAB key to make it turn into a 'chip' in the field.
next, move to the IP Address / Hostname field, and enter the IP Address that you want it accessed on. This could be the public IP, a private IP inside your network, or an IP through your VPN network (assuming you've added the host to your VPN network).
Next, move to the port field and enter the port you used on the left side of the port mapping in the override file earlier. In my case I left it as '8080', so that's what I entered in the port field.
Now enable the options for 'Block common exploits', and 'Websocket support', then go ahead and click Save.
You should see the domain / sub-domain in the list of proxy hosts. Click on the name, and it should open a new tab / browser window an dattempt to reach your Zammad site by the domain name you entered. If all has been setup properly, you'll see the button to start the setup wizard again. If you don't see that, or get an error page, make sure to check that you ahve setup the appropriate DNS A records, CNAME records, and any other items in the chain of getting a domain to resolve.
Assuming it worked as expected, we'll move forward to setting up our SSL certificate. Close the tab that opened to your wizard start button, and go back ton NPM. click the three-dot symbol to the right of your new proxy entry for zammad, and select Edit.
Now move to the SSL tab, and where it says 'None' click to view the drop-down menu, and select 'Request a New Cetriciate'. Select the options for 'Force SSL' and 'HTTP/2 Support', make sure your email is filled in, then select 'I agree', and click Save again. Give it about 10 to 30 seconds, and teh pop-up should simply close. You should now be able to access your Zammad site with SSL encrypted HTTPS.
The Setup Wizard
Depending on your email hosting functionality, you may be able to run through email setup on the wizard. If, however, you can't setup email aliases, this may be a hurdle. Don't worry, we can skip email setup in the wizrd, and do it later in the settings. You will wantn to setup a couple of emails. One for your administrator account. So run through the Wizard, and setup your admin user, then setup your Organization information. Check out the video for a thorough walk through of the Email setup, and then a good overview of the rest of the settings in Zammad.
Support My Channel and Content
Support my Channel and ongoing efforts through Patreon:
patreon.com/awesomeopensource
Buy me a Beer / Coffee:
https://paypal.me/BrianMcGonagill
No Comments