Installing the Archive Browser

You can deploy the Archive Browser as a standalone executable JAR (recommended) or as a Docker container.

Installing the Standalone Archive Browser

Follow the steps below to install the standalone Archive Browser. The standalone deployment requires no external application server. The release/ directory contains the self-contained executable JAR and configuration file.

Copy the files. To do so, copy the release/ directory to your target server. For example:

Linux: /opt/archivebrowser/

Windows: C:\archivebrowser\
Set up the system environment.

On the host, adjust the configuration (INI) file to your system environment. To do so, open the archivebrowser.ini file located in the bin/ directory and configure, at a minimum, the archive_folder and jwt_secret parameters.
Configure the SSL/TLS connection.

The application starts with HTTPS enabled out-of-the-box using a self-signed certificate. When you use certificates signed by a CA, obtain a PKCS12 (.p12) or JKS (.jks) keystore containing your certificate and private key. Copy the keystore file to the host machine and update the [SSL] section in the archivebrowser.ini file:
```
[SSL]
enabled=yes
keystore=/opt/archivebrowser/bin/my-cert.p12
keystore_password=<keystore-password>
keystore_type=PKCS12
keystore_alias=<alias-in-keystore>
```
For more information, see Configuring the Archive Browser.
Start the Archive Browser.

You have the following options to start the application, depending on your operating system:

On Linux:
- Using the command line:
  
  Navigate to the bin/ directory and start the application. Always pass the INI file explicitly so the application picks up your configuration.
  
  cd /opt/archivebrowser/bin
  
  java -jar archivebrowser.jar -INI archivebrowser.ini
- Using a system service:
  
  To start the Archive Browser automatically on system boot, create a systemd service unit. Run the application as a dedicated non-root user (for example, archivebrowser).
  
  Create the file /etc/systemd/system/archivebrowser.service:
```
[Unit]
Description=AE Archive Browser
After=network.target

[Service]
Type=simple
User=archivebrowser
WorkingDirectory=/opt/archivebrowser/bin
ExecStart=java -jar /opt/archivebrowser/bin/archivebrowser.jar -INI /opt/archivebrowser/bin/archivebrowser.ini
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable archivebrowser
sudo systemctl start archivebrowser
```
On Windows:
- Using the command line:
  
  Navigate to the bin\ directory and start the application. Always pass the INI file explicitly.
  
  cd C:\archivebrowser\bin
  
  java -jar archivebrowser.jar -INI archivebrowser.ini
Log in to the Archive Browser. Use the default credentials for your first login (UC/UC).

Important! This power user has all rights. For security reasons, change the password immediately after logging in for the first time..

Shutting Down the Archive Browser

You can shut down the Archive Browser using one of the following options, depending on your operating system:

On Linux:

Using the command line:

Send a SIGTERM to the Java process:

kill $(pgrep -f archivebrowser.jar)
Using a system service:

If you are running the application as a systemd service, use the systemctl command to stop it:

sudo systemctl stop archivebrowser

On Windows:

Using the command line:

Terminate the Java process from Task Manager or use PowerShell:

Get-WmiObject Win32_Process | Where-Object { $_.CommandLine -like '*archivebrowser.jar*' } | ForEach-Object { Stop-Process -Id $_.ProcessId }

Installing the Containerized Archive Browser (Docker)

Follow the steps below to run the Archive Browser using Docker.

Set up the system environment.

Ensure you mount volumes for the read-only archive directory and a read-write data directory for logs and the Lucene index.
Start the Archive Browser.

Run the Docker container using the following command:

docker run -d --name archivebrowser -p 8443:8080 -v /data/archives:/archives:ro -v /data/archivebrowser-data:/data -e PORT=8080 -e APP_ARCHIVE_FOLDER_LOCATION=/archives archivebrowser:<version>

Note: Replace <version> with the version number that you are installing.

Configuring TLS/SSL for Containerized Deployments

When deploying the Archive Browser via Docker, you have two options for handling SSL/TLS:

terminating SSL at a reverse proxy,
or enabling native SSL inside the container.

Option 1: Using a Reverse Proxy (Recommended)

In most containerized environments, SSL/TLS is terminated at an Ingress controller, load balancer, or reverse proxy. In this scenario, you do not need to configure SSL on the Archive Browser container itself. Use the standard Docker run command to expose the application over HTTP on port 8080, and allow your proxy to handle the HTTPS certificates.

Option 2: Enabling Native SSL in the Container

If your architecture requires the container itself to serve HTTPS traffic using your CA-signed certificate, you must mount your keystore into the container and pass the SSL configuration using environment variables.

Follow the steps below to enable native SSL:

Copy the keystore file.

Copy your PKCS12 (.p12) or JKS (.jks) keystore to a directory on your host machine that is mounted to the container, such as /data/archivebrowser-data/.
Start the Archive Browser.

Run the Docker container using the command below. Make sure you map the HTTPS port (8443), mount the directory containing your keystore, and set the required SSL environment variables.

Note: Remember to replace the placeholder paths (/data/archives, /data/archivebrowser-data/) and credentials (your-keystore-password, your-alias-in-keystore) with the actual values used in your environment. Also replace <version> with the version number that you are installing.

docker run -d --name archivebrowser -p 8443:8443 -v /data/archives:/archives:ro -v /data/archivebrowser-data:/data -e PORT=8443 -e APP_ARCHIVE_FOLDER_LOCATION=/archives -e SSL_ENABLED=yes -e SSL_KEYSTORE=/data/my-cert.p12 -e SSL_KEYSTORE_PASSWORD=your-keystore-password -e SSL_KEYSTORE_TYPE=PKCS12 -e SSL_KEYSTORE_ALIAS=your-alias-in-keystore archivebrowser:<version>