Ubuntu 24.04 LTS#

This chapter describes a streamlined installation method for Allegra on Ubuntu 24.04 LTS and other modern Linux distributions using a pre-packaged ZIP archive.

The installation uses a convenient management script (allegra.sh) that handles all aspects of Allegra lifecycle management.

Preparation#

Permissions#

You must have the following permissions on your Linux system:

Permission to download and extract files
Permission to run shell scripts
Sudo privileges (only if installing as a systemd service)

Hardware Requirements#

Make sure your system meets the hardware requirements for your expected number of users.

Software Requirements#

Before starting the installation, ensure you have:

Java 21 or higher installed and available in your PATH.
```
# Install OpenJDK 21 on Ubuntu 24.04
sudo apt update
sudo apt install openjdk-21-jdk
```
You can also download Java from Adoptium.
Sufficient disk space:
- At least 500 MB for the Allegra application
- Additional space for ALLEGRA_HOME (1-10 GB depending on usage)
Available network port (default 8080) - ensure no other services are using it
Database server - You need access to one of the supported database systems:
- PostgreSQL (recommended for Linux)
- MySQL/MariaDB
- Microsoft SQL Server
- Oracle
- Firebird (for testing only)
Follow the database setup instructions to create an empty database before installing Allegra.
System utilities (usually pre-installed):
- curl or wget - for downloading files
- unzip - for extracting ZIP archives and reading JAR files
- sha256sum - for verifying script updates
```
# Install if needed
sudo apt install curl unzip coreutils
```

Installation Steps#

Step 1: Download the ZIP Package#

Download the Allegra ZIP package from:

https://alltena.com/allegra.zip

Save the file to a location of your choice, for example /tmp/allegra.zip.

cd /tmp
wget https://alltena.com/en/resources/downloads

Or using curl:

cd /tmp
curl -L -O https://alltena.com/en/resources/downloads

Step 2: Extract the ZIP File#

Extract the ZIP file to a location that works best for your environment.

Default installation location: /home/ubuntu/allegra

This is the recommended location for most installations. If using a different user, replace ubuntu with your username.

mkdir -p /home/ubuntu/allegra
cd /home/ubuntu/allegra
unzip /tmp/allegra.zip

After extraction, your directory should contain:

allegra.sh - Management script
bin/ - Directory containing allegra.jar
conf/ - Configuration directory with application.properties
allegra.service - Systemd service template

Step 3: Make Script Executable#

Ensure the management script has execute permissions:

chmod +x allegra.sh

Step 4: Verify Java Installation#

Verify that Java is installed and accessible:

./allegra.sh check-java

This will display your installed Java version. You should see output similar to:

openjdk 21.0.8 2025-07-15 LTS
OpenJDK Runtime Environment Temurin-21.0.8+9 (build 21.0.8+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.8+9 (build 21.0.8+9-LTS, mixed mode, sharing)

If Java is not found, install it and ensure it’s in your PATH.

Step 5: Run Initial Configuration#

Allegra provides a complete installation wizard that guides you through all configuration steps:

./allegra.sh install

This interactive wizard will configure:

Allegra Home Directory - Where attachments and data are stored (recommended: /home/ubuntu/allegra/allegra-home)
Database Connection - Connection details for your database
Server Settings - Port and context path configuration
Memory Settings - Java heap memory allocation

Follow the prompts carefully and provide the requested information.

Alternatively, you can configure each component separately (see Configuration Commands below).

Step 6: Start Allegra#

After configuration is complete, start Allegra:

./allegra.sh start

The script will display:

Starting bin/allegra.jar with memory: Xms=1024m Xmx=2048m
Started with PID 12345
Memory settings: Xms=1024m Xmx=2048m
Configuration: conf/application.properties
You can check the logs in allegra-startup.log and in the ALLEGRA_HOME/log folder.

Step 7: Access Allegra#

After starting, wait 1-2 minutes for Allegra to initialize, then open your web browser and navigate to:

http://localhost:8080

If you configured a different port or context path, adjust the URL accordingly.

The default login credentials are:

Username: admin
Password: tissi

Attention

Change the default admin password immediately after your first login!

Management Commands#

The allegra.sh script provides comprehensive management capabilities. All commands are executed by running ./allegra.sh followed by the command name.

Application Lifecycle Commands#

start#

Starts the Allegra application in the background.

./allegra.sh start

Features:

Checks if application is already running
Reads memory settings from conf/application.properties
Starts Java process in background using nohup
Creates PID file for process tracking
Logs output to allegra-startup.log

Example output:

Starting bin/allegra.jar with memory: Xms=1024m Xmx=2048m
Started with PID 12345
Memory settings: Xms=1024m Xmx=2048m
Configuration: conf/application.properties
You can check the logs in allegra-startup.log and in the ALLEGRA_HOME/log folder.

stop#

Stops the running Allegra application gracefully.

./allegra.sh stop

Features:

Sends SIGTERM signal for graceful shutdown
Removes PID file after stopping
Validates process exists before attempting to stop

Example output:

Stopping application with PID 12345...
Stopped.

status#

Shows the current status of the Allegra application.

./allegra.sh status

When running:

Allegra is running with PID 12345
Running jar: bin/allegra.jar
Log file: allegra-startup.log
Additional logs: Check ALLEGRA_HOME/log folder

When stopped:

Allegra is not running

Configuration Commands#

install#

Runs the complete installation wizard that configures all aspects of Allegra.

./allegra.sh install

This interactive command runs through four configuration steps:

Home Directory Setup - Configure ALLEGRA_HOME
Database Connection - Set up database connection parameters
Server Configuration - Configure port and context path
Memory Settings - Set Java heap memory allocation

After completion, displays the final configuration and instructions to start Allegra.

setup-home#

Configure the Allegra home directory where data files, attachments, and templates are stored.

./allegra.sh setup-home

Recommended location: /home/ubuntu/allegra/allegra-home

Interactive prompts:

Absolute path to home directory (or . for current directory)
Creates directory if it doesn’t exist
Validates directory is writable
Updates allegra.home in conf/application.properties

Example:

Define Allegra Home folder absolute path.
Allegra stores in this folder all important data files like attachments templates etc.
Make sure the folder is writable.

Enter absolute path (or . for current directory): /home/ubuntu/allegra/allegra-home
Updated allegra.home in application.properties to: /home/ubuntu/allegra/allegra-home

setup-db#

Configure database connection parameters interactively.

./allegra.sh setup-db

Supported databases:

PostgreSQL
MySQL
Microsoft SQL Server
Oracle
Firebird (testing only)

Interactive prompts:

Database type selection
Database host (default: localhost)
Database port (default varies by database type)
Database name or Oracle SID
Database username
Database password (hidden input)

Configuration updates:

Updates the following properties in conf/application.properties:

allegra.db.username
allegra.db.password
allegra.db.adapter
allegra.db.driver
allegra.db.url

Example:

Define Allegra database connection information
Choose a database vendor:
[1] PostgreSQL
[2] MySQL
[3] MSSQL
[4] Oracle
[5] Firebird (Only for testing)

Enter choice [1-5]: 1
Selected: postgresql

Database host [localhost]: db.example.com
Database port [5432]: 5432
Database name: allegra
Database username: allegra_user
Database password: ********

Database configuration:
=======================
Type: postgresql
Host: db.example.com
Port: 5432
Database: allegra
Username: allegra_user
URL: jdbc:postgresql://db.example.com:5432/allegra

Update application.properties with these settings? (y/n): y
Updated application.properties successfully!

setup-server#

Configure Allegra server settings including port and context path.

./allegra.sh setup-server

Interactive prompts:

Server port (default: 8080)
Server context path (default: /)

Configuration updates:

Updates the following properties in conf/application.properties:

server.port
server.servlet.context-path

Example:

Define Allegra server configuration

Server port [8080]: 9090
Server context path [/]: /allegra

Server configuration:
====================
Port: 9090
Context path: /allegra

Update application.properties with these settings? (y/n): y
Updated server configuration in application.properties successfully!

setup-memory#

Configure Java heap memory allocation for Allegra.

./allegra.sh setup-memory

Interactive prompts:

Total memory allocation in megabytes (default: 2048)
Minimum: 512 MB
Validates reasonable values
Calculates Xms (initial heap) as 50% of total
Sets Xmx (maximum heap) to total value

Configuration updates:

Updates allegra.server.memory in conf/application.properties.

Example:

Define Allegra server memory configuration

How much memory do you want to allocate for Allegra (in megabytes)? [2048]: 4096

Memory configuration:
====================
Total memory: 4096 MB
Initial heap (Xms): 2048 MB
Maximum heap (Xmx): 4096 MB

Update application.properties with these settings? (y/n): y
Updated memory configuration in application.properties successfully!

show-config#

Display the current contents of conf/application.properties.

./allegra.sh show-config

This command outputs the entire configuration file to the console for review.

Information Commands#

check-java#

Check if Java is installed and display the version information.

./allegra.sh check-java

Example output:

Java version:
openjdk version "11.0.16" 2022-07-19
OpenJDK Runtime Environment (build 11.0.16+8-post-Ubuntu-0ubuntu120.04)
OpenJDK 64-Bit Server VM (build 11.0.16+8-post-Ubuntu-0ubuntu120.04, mixed mode)

version#

Display the installed Allegra version by reading Version.properties from the JAR file.

./allegra.sh version

Example output:

Allegra version is 900b59

Update Commands#

update#

Update Allegra to the latest available version.

./allegra.sh update

Attention

CRITICAL: Updating Allegra requires replacing the allegra.jar file.

Before running any update, you MUST create backups of:

The complete database - Full database backup
ALLEGRA_HOME directory - All attachments, templates, and configuration files

This ensures you can recover if any issues occur during the update.

What gets updated:

When you run the update command, only the bin/allegra.jar file is replaced with the new version. All your configuration, data, and settings remain unchanged.

For detailed update instructions, including:

Step-by-step backup procedures
Manual update process
Rollback procedures
Troubleshooting update issues
Best practices for production updates

See: Updating Allegra

check-script-updates#

Check if there are updates available for the management script itself.

./allegra.sh check-script-updates

Example output:

Checking for script updates...
Script update available!
Current checksum:  abc123def456...
Available checksum: def789ghi012...

There is an update for the script. Please download the latest version.

update-script#

Update the management script (allegra.sh) to the latest version.

./allegra.sh update-script

Process:

Fetches latest script checksum from server
Compares with current script checksum
Prompts for confirmation
Downloads new script to temporary file
Verifies downloaded checksum
Creates backup of current script (allegra.sh.backup)
Replaces script with new version

Example output:

Checking for script updates...
Script update available!
Current checksum:  abc123...
Available checksum: def456...

Do you want to update the script? (y/n): y

Downloading updated script...
Created backup: allegra.sh.backup
Script updated successfully!
New checksum: def456...

Please run the script again to use the updated version.

Systemd Service Commands#

install-service#

Install Allegra as a systemd service for automatic startup and management.

sudo ./allegra.sh install-service

Note

This command requires root privileges (sudo).

Requirements:

allegra.service template file must be present
systemd must be available on the system
Root/sudo access

Process:

Verifies systemd is available
Gets current installation directory
Identifies the user who will run the service
Updates service template with correct paths and user
Displays service configuration for review
Prompts for confirmation
Installs service file to /etc/systemd/system/allegra.service
Reloads systemd daemon
Enables service to start on boot

Example output:

Installing Allegra as a systemd service

Installation directory: /home/ubuntu/allegra
Service will run as user: ubuntu

Service configuration:
=====================
[Unit]
Description=Allegra Workmanagement Software
Wants=network-online.target
After=network-online.target

[Service]
Type=forking
User=ubuntu
WorkingDirectory=/home/ubuntu/allegra
ExecStart=/home/ubuntu/allegra/allegra.sh start
ExecStop=/home/ubuntu/allegra/allegra.sh stop
PIDFile=/home/ubuntu/allegra/allegra.pid
Restart=on-failure
RestartSec=5
TimeoutStartSec=60
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

Install service with these settings? (y/n): y
Installing service file to /etc/systemd/system/allegra.service...
Reloading systemd daemon...
Service file installed successfully!
Enabling service to start on boot...
Service installed and enabled successfully!

Other available commands:
  sudo systemctl stop allegra      - Stop the service
  sudo systemctl restart allegra   - Restart the service
  sudo systemctl status allegra    - Check service status
  sudo systemctl disable allegra   - Disable service from starting on boot
  sudo journalctl -u allegra -f    - View service logs

To start the service, run:
  sudo systemctl start allegra

Important

Once installed as a service, you should use systemd commands to manage Allegra:

sudo systemctl start allegra - Start the service
sudo systemctl stop allegra - Stop the service
sudo systemctl restart allegra - Restart the service
sudo systemctl status allegra - Check status
sudo journalctl -u allegra -f - View live logs

uninstall-service#

Uninstall the Allegra systemd service.

sudo ./allegra.sh uninstall-service

Process:

Checks if service file exists
Prompts to stop if service is running
Disables service if enabled
Removes service file from /etc/systemd/system/
Reloads systemd daemon

Example output:

Uninstalling Allegra systemd service

Service is currently running
Stop the service before uninstalling? (y/n): y
Stopping service...
Disabling service...
Removing service file...
Reloading systemd daemon...
Service uninstalled successfully!

help#

Display usage information and list all available commands.

./allegra.sh help

Script Features#

The allegra.sh Bash script provides:

POSIX-compatible - Works on most Linux/Unix systems
PID file management - Tracks running processes via allegra.pid
Configuration in Java properties - Uses conf/application.properties
Automatic updates - Built-in update mechanism for both Allegra and the script
Version checking - SHA256 checksums verify updates
Process management - Graceful shutdown using SIGTERM
Memory management - Configurable heap settings with validation
Systemd integration - Easy service installation for production deployments

Configuration File Location#

All configuration is stored in:

conf/application.properties

This file uses standard Java properties format and includes settings for:

Database connection
Server port and context path
Allegra home directory
Memory allocation
Additional Spring Boot properties

Key Properties#

# Allegra home directory
allegra.home=/home/ubuntu/allegra/allegra-home

# Database configuration
allegra.db.adapter=postgresql
allegra.db.driver=org.postgresql.Driver
allegra.db.url=jdbc:postgresql://localhost:5432/allegra
allegra.db.username=allegra
allegra.db.password=secret

# Server configuration
server.port=8080
server.servlet.context-path=/

# Memory configuration (in MB)
allegra.server.memory=2048

Log Files#

Allegra generates several log files:

allegra-startup.log - Application startup output (in Allegra installation directory)
ALLEGRA_HOME/log/*.log - Detailed application logs (in home directory)
ALLEGRA_HOME/log/allegra.log - Main application log

For systemd service installations, also check:

sudo journalctl -u allegra - Systemd journal logs
sudo journalctl -u allegra -f - Follow live logs

To troubleshoot issues, check these log files in order.

Common Usage Scenarios#

Quick Start (Interactive)#

For first-time installation:

cd /home/ubuntu/allegra
./allegra.sh install
./allegra.sh start

Browse to http://localhost:8080 and log in with admin/tissi.

Development Setup#

For development with custom port and context:

./allegra.sh setup-server
# Enter port: 9090
# Enter context: /allegra-dev
./allegra.sh start

Access at http://localhost:9090/allegra-dev

Production Setup with Systemd Service#

For production deployment:

# Configure everything
./allegra.sh install

# Test the configuration
./allegra.sh start
# Verify everything works, then stop
./allegra.sh stop

# Install as systemd service
sudo ./allegra.sh install-service

# Start the service
sudo systemctl start allegra

# Check status
sudo systemctl status allegra

# Service is now running and will start automatically on boot

Updating Production Instance#

Attention

Before updating, ALWAYS backup your database and ALLEGRA_HOME directory.

For complete update instructions, see: Updating Allegra (Ubuntu ZIP)

Quick update command:

# Backup database and ALLEGRA_HOME first!
./allegra.sh update
# Follow the prompts

If running as a service:

# Backup database and ALLEGRA_HOME first!
sudo systemctl stop allegra
./allegra.sh update
sudo systemctl start allegra

Changing Memory Allocation#

./allegra.sh stop
./allegra.sh setup-memory
# Enter new memory value
./allegra.sh start

Or if running as a service:

sudo systemctl stop allegra
./allegra.sh setup-memory
# Enter new memory value
sudo systemctl start allegra

Troubleshooting#

Application Won’t Start#

Check Java installation:
```
./allegra.sh check-java
```

Check if port is already in use:

sudo netstat -tulpn | grep :8080

Or using ss:

sudo ss -tulpn | grep :8080

Review startup logs:
```
cat allegra-startup.log
```
Check application logs:
```
tail -f $ALLEGRA_HOME/log/allegra.log
```

Verify database connectivity:

Ensure your database server is running and accessible:

# For PostgreSQL
pg_isready -h localhost -p 5432

# For MySQL
mysqladmin ping -h localhost

Application Won’t Stop#

If ./allegra.sh stop doesn’t work:

Find the Java process manually:
```
ps aux | grep allegra.jar
```
Kill the process by PID:
```
kill <PID>
```
If that doesn’t work, force kill:
```
kill -9 <PID>
```
Remove stale PID file:
```
rm -f allegra.pid
```

Script Permission Denied#

If you get “Permission denied” when running the script:

chmod +x allegra.sh
./allegra.sh help

Out of Memory Errors#

If you see OutOfMemoryError in logs:

Stop Allegra
Increase memory allocation:
```
./allegra.sh setup-memory
```
Restart Allegra

Database Connection Errors#

If Allegra can’t connect to the database:

Verify database server is running:

# PostgreSQL
sudo systemctl status postgresql

# MySQL
sudo systemctl status mysql

Check firewall settings:

# Check if firewall is blocking
sudo ufw status

Verify database credentials:
```
./allegra.sh show-config
```

Test database connection:

# PostgreSQL
psql -h localhost -U allegra_user -d allegra

# MySQL
mysql -h localhost -u allegra_user -p allegra

Systemd Service Issues#

If the systemd service won’t start:

Check service status:
```
sudo systemctl status allegra
```
View detailed logs:
```
sudo journalctl -u allegra -n 50
```
Verify service file:
```
sudo systemctl cat allegra
```
Check file permissions:
```
ls -la /home/ubuntu/allegra/allegra.sh
ls -la /home/ubuntu/allegra/allegra.pid
```
The user specified in the service file must have write access to these files.

Manually test the script:

cd /home/ubuntu/allegra
./allegra.sh start
./allegra.sh status

Security Considerations#

For Production Deployments#

This ZIP package installation is suitable for internal networks and development. For production deployments accessible from the Internet, you should:

Use a reverse proxy (Apache, Nginx) in front of Allegra
- See Apache as proxy
- See Nginx as proxy
Enable HTTPS/SSL - Never expose Allegra directly over HTTP to the Internet

Configure firewall - Restrict access to the Allegra port

# Allow only from specific IP
sudo ufw allow from 192.168.1.0/24 to any port 8080

# Or allow from localhost only
sudo ufw deny 8080
# Access via reverse proxy on port 80/443

Regular updates - Use ./allegra.sh update to keep Allegra current
Strong passwords - Change default admin password immediately
Database security - Use strong database passwords and restrict network access

Regular backups - Backup both database and ALLEGRA_HOME directory

# Database backup (PostgreSQL)
pg_dump -U allegra_user allegra > allegra_backup_$(date +%Y%m%d).sql

# ALLEGRA_HOME backup
tar -czf allegra-home_$(date +%Y%m%d).tar.gz $ALLEGRA_HOME

Systemd Service Security#

When running as a systemd service:

The service runs under a dedicated user account (not root)

Consider creating a dedicated allegra user:

sudo useradd -r -s /bin/false allegra
sudo chown -R allegra:allegra /home/ubuntu/allegra
sudo chown -R allegra:allegra /home/ubuntu/allegra/allegra-home

Update the service file to use this user before installation
Ensure the service user has minimal system privileges

File Permissions#

Recommended file permissions:

# Installation directory
chmod 755 /home/ubuntu/allegra
chmod 755 /home/ubuntu/allegra/bin

# Management script
chmod 755 /home/ubuntu/allegra/allegra.sh

# Configuration files
chmod 640 /home/ubuntu/allegra/conf/application.properties

# ALLEGRA_HOME directory
chmod 750 /home/ubuntu/allegra/allegra-home
chmod 640 /home/ubuntu/allegra/allegra-home/Torque.properties

Next Steps#

After successful installation, you should:

Change admin password - Log in and change the default password immediately
Configure SMTP - Set up email server for notifications See configuration guide

Configure backups - Set up automated database and file backups

Create a backup script:

#!/bin/bash
# /home/ubuntu/allegra/backup.sh

BACKUP_DIR="/backup/allegra"
DATE=$(date +%Y%m%d_%H%M%S)

# Database backup
pg_dump -U allegra_user allegra | gzip > "$BACKUP_DIR/db_$DATE.sql.gz"

# ALLEGRA_HOME backup
tar -czf "$BACKUP_DIR/home_$DATE.tar.gz" /home/ubuntu/allegra/allegra-home

# Keep only last 7 days
find "$BACKUP_DIR" -type f -mtime +7 -delete

Schedule with cron:

# Daily backup at 2 AM
0 2 * * * /home/ubuntu/allegra/backup.sh

Review security - Configure firewall and set up reverse proxy

Monitor logs - Set up log rotation and monitoring

# Check log rotation
sudo nano /etc/logrotate.d/allegra

/home/ubuntu/allegra/allegra-home/log/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 allegra allegra
}

Customize Allegra - Configure projects, users, and workflows See the Allegra User Guide
Optional: Set up Gantt printing - See Gantt Chart Print Server

Ubuntu 24.04 LTS

Contents

Ubuntu 24.04 LTS#

Preparation#

Permissions#

Hardware Requirements#

Software Requirements#

Installation Steps#

Step 1: Download the ZIP Package#

Step 2: Extract the ZIP File#

Step 3: Make Script Executable#

Step 4: Verify Java Installation#

Step 5: Run Initial Configuration#

Step 6: Start Allegra#

Step 7: Access Allegra#

Management Commands#

Application Lifecycle Commands#

start#

stop#

status#

Configuration Commands#

install#

setup-home#

setup-db#

setup-server#

setup-memory#

show-config#

Information Commands#

check-java#

version#

Update Commands#

update#

check-script-updates#

update-script#

Systemd Service Commands#

install-service#

uninstall-service#

help#

Script Features#

Configuration File Location#

Key Properties#

Log Files#

Common Usage Scenarios#

Quick Start (Interactive)#

Development Setup#

Production Setup with Systemd Service#

Updating Production Instance#

Changing Memory Allocation#

Troubleshooting#

Application Won’t Start#

Application Won’t Stop#

Script Permission Denied#

Out of Memory Errors#

Database Connection Errors#

Systemd Service Issues#

Security Considerations#

For Production Deployments#

Systemd Service Security#

File Permissions#

Next Steps#