Installation and Configuration¶
Info
The Docker-based installation applies only to the ENTERPRISE subscription with on-premise hosting.
This guide describes the installation and configuration of calServer in a Docker environment on a Linux system (e.g., Ubuntu 24.04). It is intended for IT administrators and covers all essential steps from setting up the Docker environment to the initial database setup.
Prerequisites¶
- Operating System: Ubuntu 24.04 or comparable Linux distribution
- User Permissions: Administrator or sudo rights, or user in the Docker group
- Network: Open ports (80, 443, SSH) and configured firewall
- Software: Git, Docker Engine, Docker Compose Plugin
- System Resources: See System Requirements
Installing Docker and Docker Compose¶
If Docker is not yet installed:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker
sudo apt install docker-compose-plugin
docker --version
docker compose version
Installing calServer¶
Preparing the Working Directory¶
If you map the data directory externally, ensure that the required directory structure exists. Otherwise, /data/calserver will be created automatically with the following structure:
sudo mkdir -p /data/calserver /data/calserver/filemanager/dms /data/calserver/filemanager/inbox /data/calserver/filemanager/reports /data/calserver/local
Cloning the Repository¶
sudo apt install git
git clone https://calhelp@bitbucket.org/calserver/calserver-start.git
cd calserver-start
Running the Installer¶
The installation script copies all Compose files, shell scripts, and the .env template to the master directory and sets up an autostart service under /var/calserver/deploy:
For existing installations, alternatively use:
Adjusting Configuration¶
Switch to the master directory and open the .env file:
Adjust the following entries in particular:
IMAGE_TAG=release-latest
YII_DEBUG=false
DOMAIN=mycompany.calserver.com
SUBSCRIPTION=EXPERT
LETSENCRYPT=true
LETSENCRYPT_EMAIL=admin@mycompany.com
DOCKER_PATH=/var/calserver
SSL_CERT_PATH=/var/calserver/ssl
DB_HOST=mysql_db
DB_ROOT_PASSWORD=MyCompanyRoot!23
DB_DATABASE=calserver
DB_USER=root
DB_PASSWORD=MyCompanyDB!45
MYSQL_DATA_PATH=/data/mysql
BORG_PASSPHRASE=MyCompanyBorg!67
BORG_REMOTE=
BORG_REMOTE_PASS=
BORG_REPO_DIR=
STORAGE_BORG_BACKUP=
FILE_MANAGER_PATH=/data/calserver/filemanager
DMS_PATH=/data/calserver/filemanager/dms
INBOX_PATH=/data/calserver/filemanager/inbox
REPORTS_PATH=/data/calserver/filemanager/reports
LOCAL_PATH=/data/calserver/local
CALSERVER_HOST=mycompany.calserver.com
Warning
Replace the example passwords with secure, individual passwords. The values shown here are for illustration purposes only.
Update and Deployment¶
Loading Container Images¶
A Docker Hub login is required for the download, which is provided through your subscription:
Performing Deployment¶
Check the container status:
After deployment, the application is accessible under the configured domain and displays the database initialization message.
Database Setup in the MySQL Container¶
After the first deploy.sh, you need to create the database and user in the MySQL container.
Connect to the MySQL container:
Execute the following SQL commands (use values from .env):
CREATE DATABASE calserver;
CREATE USER 'calhelp'@'%' IDENTIFIED BY 'MyCompanyDB!45';
GRANT ALL PRIVILEGES ON calserver.* TO 'calhelp'@'%';
FLUSH PRIVILEGES;
EXIT;
Warning
Completely exit the Docker exec session with exit before proceeding.
Restart calServer:
Setting Up calServer V2¶
The V2 components (Laravel API + Nuxt Frontend + Redis) are provided via the additional Compose file docker-compose.v2.yml.
Initial Setup¶
On the first start of the calserver-api-v2 container, the following are automatically performed:
- Database migrations are executed (
artisan migrate) - RBAC operations and groups are created (
artisan app:setup) - A super admin user is created:
- Email:
- Password:
Warning
Change the default password of the super admin user after the first login.
Starting V2 Containers¶
Checking V2 Container Status¶
docker ps --filter "name=calserver-api-v2"
docker ps --filter "name=calserver-frontend"
docker ps --filter "name=calserver-redis"
Manual Setup (Existing Installation)¶
If the V2 database is built on an existing V1 database and the login does not work, run the setup manually:
The command is idempotent — already existing entries are skipped.
Viewing V2 Logs¶
Firewall Configuration (UFW)¶
sudo apt install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
Data Transfer Between Systems¶
Transferring File Data¶
One-time copy:
Synchronization (recommended):
Transferring the Database¶
Export from the source server:
Import on the target server:
Or combined:
mysqldump -h YourSourceIP -uYourDBUserSource -pYourDBPassSource [DatabaseName] | mysql -h localhost -uYourDBUserTarget -pYourDBPassTarget [DatabaseName]
Troubleshooting¶
For problems during installation or operation:
- Check container status:
docker ps - View log output:
docker logs <container-name> - Check working directory:
pwd - Test network and firewall: Ports 80, 443, 22 must be open
- Check permissions: sudo rights or Docker group
For further troubleshooting, see Troubleshooting.