Windows Installation

Windows Installation#

This chapter describes a streamlined installation method for Allegra on Windows systems using a pre-packaged ZIP file from our resources page. For updating Allegra to a newer version, see Updating Allegra.

Attention

This guide is not intended to make your server secure for public access over the Internet. Additional individual security measures are required for that purpose.

Preparation#

Before you begin the installation, ensure you have the following:

Installation#

Follow these steps to install Allegra on Windows using the ZIP package.

  1. Download the ZIP package from the Allegra resources page.

  2. Extract the ZIP file to a folder (e.g., C:\allegra). This will be your installation directory, referenced as <INSTALLATION_DIRECTORY>.

  3. Run allegra.bat install from within <INSTALLATION_DIRECTORY> to start the setup wizard.

  4. Follow the prompts to configure the home directory, database, server, and memory settings (these correspond to entries in conf/application.properties).

  5. (Optional) Install Allegra as a Windows service: Run allegra.bat install-service for automatic startup after reboot (enter same memory settings as during installation).

  6. Access Allegra in your browser at http://localhost:8080 (or your configured port) and log in with:

    • Username: admin

    • Password: tissi

Note

The <INSTALLATION_DIRECTORY> contains Allegra’s program files and scripts. During setup, Allegra also creates a separate <ALLEGRA_HOME> directory where Allegra stores all attachments and configuration files.

Ensure that Java 21 JRE/JDK and a supported database server are installed before running the installer. Change the default admin password immediately after your first login.

Operation#

Manual Startup and Shutdown#

To start, stop, or check the status of Allegra manually, open a Command Prompt in the installation directory and run:

cd <INSTALLATION_DIRECTORY>
allegra.bat start
allegra.bat stop
allegra.bat status

Managing Allegra as a Windows Service#

If Allegra is installed as a Windows service, you can control it through the Windows Services Manager.

Windows Services Manager showing Allegra service

Windows Services Manager showing the Allegra service.#

Automatic Startup#

When installed as a service, Allegra starts automatically each time Windows boots.

To remove the Allegra Windows service, run:

allegra.bat uninstall-service

Updating#

To update Allegra to a newer version, see Updating Allegra.

Next Steps#

After successful installation, you should:

  1. Secure access

    • Log in and change the default admin password immediately.

    • Review firewall settings and restrict access to the Allegra port.

    • For Internet-facing deployments, use a reverse proxy (Apache, Nginx, IIS) and enable HTTPS/SSL.

      See:

  2. Configure backups

    • Configure regular backups for both the database and the ALLEGRA_HOME directory.

  3. Customize Allegra

    • Configure projects, users, and workflows.

    • See the Allegra User Guide.

  4. Maintain your installation

    • Keep Allegra up to date using allegra.bat update.

    • Use strong database passwords and limit database network access.

  5. Optional

Troubleshooting#

Application Won’t Start#

  1. Check Java installation:

    allegra.bat check-java

  2. Check if the default port (8080) is already in use:

    netstat -an | findstr :8080

  3. Review the startup log:

    <INSTALLATION_DIRECTORY>\allegra-startup.log

  4. Check the application log:

    Review <ALLEGRA_HOME>\log\catalina.out for detailed error messages.

  5. Verify database connectivity:

    Ensure your database server is running and reachable from the Allegra host.

Setting JAVA_HOME#

If Allegra cannot find your Java installation, you may need to add the Java installation directory to your system PATH, in this windows this can be done via the User Interface:

Assuming you have downloaded a Java 21 JRE/JDK in C:\Program Files\Java\jdk-21:

  1. Add JAVA_HOME in two places under Windows Environment Variables:

    • In the User variables section, click “New” and add: - Variable name: JAVA_HOME - Variable value: C:\Program Files\Java\jdk-21

    • In the System variables section, click “New” and add: - Variable name: JAVA_HOME - Variable value: C:\Program Files\Java\jdk-21

Windows Environment Variables showing JAVA_HOME

Setting the JAVA_HOME variable in Windows Environment Variables.#

  1. Add JAVA_HOME to two paths in the PATH variable:

    • In the User variables section, find the “Path” variable, select it and click “Edit”. Click “New” and add: %JAVA_HOME%\bin

    • In the System variables section, find the “Path” variable, select it and click “Edit”. Click “New” and add: %JAVA_HOME%\bin

Windows Environment Variables showing JAVA_HOME in PATH

Setting the PATH variable in Windows Environment Variables.#

  1. Click “OK” to save all changes.

Note

You need to restart your Command Prompt or system for changes to take effect. Rickt clicking on your home screen and “Refresh” might also work for the changes to take effect.

Out of Memory Errors#

If you encounter an OutOfMemoryError in the logs:

  1. Stop Allegra:

    allegra.bat stop

  2. Increase the memory allocation:

    allegra.bat setup-memory
# Enter a higher memory value when prompted

  3. Restart Allegra:

    allegra.bat start

Database Connection Errors#

If Allegra cannot connect to the database:

  1. Ensure the database server is running.

  2. Check firewall and network settings.

  3. Verify database credentials and configuration:

    allegra.bat show-config

  4. Test the connection using a database client tool.

  5. For MS SQL Server, ensure the SQL Server Browser service is running.

Additional Commands#

Following useful commands are available in the <INSTALLATION_DIRECTORY>:

allegra.bat help                 # Display help information
allegra.bat setup-home           # Configure Allegra home directory
allegra.bat setup-db             # Configure database connection
allegra.bat setup-server         # Configure server settings
allegra.bat setup-memory         # Configure memory settings
allegra.bat show-config           # Display current configuration
allegra.bat check-java           # Verify Java installation
allegra.bat version              # Display current version
allegra.bat update               # Update Allegra to latest version
allegra.bat update-script        # Update allegra.ps1 script to latest version
allegra.bat check-script-updates # Check update script version
allegra.bat install-service      # Install Allegra as a Windows service
allegra.bat uninstall-service    # Remove Allegra from Windows services

Key Properties#

The following important configuration properties are stored in <INSTALLATION_DIRECTORY>\conf\application.properties:

# Allegra home directory
allegra.home=C:\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, e.g., 2048 = 2GB or 4096 = 4GB)
allegra.server.memory=2048