Zammad - Developer Guide

Learn how to install and configure Zammad on AWS with our step-by-step deployment guide. This comprehensive resource walks you through provisioning your cloud environment, securely deploying Zammad, and operating it reliably in a self-hosted AWS environment. Whether you're consolidating support tickets from email and chat, building a searchable knowledge base, or replacing a hosted help desk subscription, this guide will help you set up and run Zammad efficiently in the cloud.

Zammad pairs well with the rest of a self-hosted support stack - if your team already runs a team chat tool for internal communication, Zammad handles the customer-facing side without sending ticket data to a third party. Let's get started deploying Zammad on AWS.

Launching the AMI

Step 1: Find and Select the Zammad AMI

1. Log in to your AWS Management Console.
2. Navigate to 'Zammad' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy Zammad" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail" used for SSL certificate generation.
3. Enter a value for "DeploymentName".
4. Provide a public domain for "DomainName". Zammad will automatically try to set up SSL if the domain is hosted on Route53. If unsuccessful, you must set up SSL manually.
5. Choose an instance type "InstanceType" (Recommended: t3a.xlarge, since Zammad's Elasticsearch and Redis services need more headroom than a single-service AMI).
6. Select your preferred "KeyName".
7. Provide an S3 bucket name for "S3Bucket", used for storing PostgreSQL database backups.
8. Set "SSHLocation" to 0.0.0.0/0.
9. Keep "SubnetCidrBlock" as 10.0.0.0/24.
10. Keep "VpcCidrBlock" as 10.0.0.0/16.
11. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the details you've entered. Here's an example of a completed set of stack parameters:

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. Please wait for 5-10 minutes until the stack has been successfully created.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name and paste the copied PublicIp into the value textbox.
4. Click "Save".

Access Zammad

Access Zammad using the "DashboardUrl" or "DashboardUrlIp" provided in the Outputs tab.

On first access, Zammad walks you through its onboarding wizard instead of a plain login form.

Click "Set up a new system" to create your admin account and complete the initial configuration. If your team already runs a centralized identity provider, Zammad also supports SAML and OAuth2 login - see our Authentik developer guide if you want to put Zammad behind the same SSO your other self-hosted tools use.

Generate SSL Manually

Zammad will automatically try to set up SSL when a Route53-hosted domain is provided. If it fails, follow these steps to generate SSL manually.

Step 1: Copy IP Address

Follow the Update DNS steps above, if not already done, and copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run: ssh -i <your key name> ubuntu@<Public IP address>
3. Type "yes" and press Enter to confirm.

Step 3: Generate SSL

Run the following command and follow the prompts:

sudo /root/certificate_generate_standalone.sh

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

sudo docker ps

sudo docker logs <container-id-prefix>

Shutting Down Zammad

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the Zammad instance from the Instance state dropdown. You can restart it later as needed.

Remove Zammad

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete".

Upgrades

When a new version is available in AWS Marketplace, remove the previous deployment after backing up necessary server data, and relaunch with the new version.

Troubleshoot

1. If you face vCPU quota limits, request an increase: How to increase AWS quota.

2. If you face insufficient capacity errors while creating the stack, try another region or time.

Check whether the instance storage is full - Zammad's Elasticsearch index can grow quickly on busy support desks.

• Log into the server and run:

df -h

• If the root volume is between 90-100%, resize the EBS volume (per AWS docs), then reboot and restart the service.

Conclusion

The Meetrix Zammad Deployment Guide helps you integrate a self-hosted help desk into your AWS environment. Whether you're a DevOps engineer, support lead, or IT administrator, this guide provides step-by-step instructions for a secure and reliable setup. For a broader look at self-hosting business software on AWS, see our ERPNext developer guide or our roundup of collaboration tools on AWS Marketplace.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with Zammad issues.

For questions about Zammad itself rather than the AWS deployment, the official Zammad documentation, the Zammad GitHub repository, and zammad.com are the best starting points.