System requirements

Memory: 16GB

Disk space: 20GB (depending on archive size)

A CPU that supports AVX

Default credentials

Keycloak administration panel

http://localhost/auth/

username: admin, password: am

Predefined users in ASTA 7:

username: sys_admin, password: am,

username: test_user, password: am

Prerequisites

For a development or test environment, it is possible to use Docker Desktop. Follow the instructions for your operating system at:

https://docs.docker.com/get-docker/

For a server/production environment, we recommend Docker Engine with the Docker Compose plug-in and Ubuntu LTS:

https://docs.docker.com/engine/install/ubuntu/

Data persistence

The data inserted will be removed if you remove the attached volumes. (docker compose down -v)

If you want to stop the containers but keep your local changes only use docker compose down.

This applies to all application data including security settings in Keycloak.

Guide

Access to the solution

Goto http://localhost/

Project files

asta7_*: Contains files to run the application and environment settings. (docker-compose.yml and .env)

templates: Contains templates to use with the application

arkiv: Archive for testing with digital documents.

Docker images

To access Stiftelsen Asta docker images you need to have a docker user with access granted. With this user you need to login to your local docker instance.

To log in using the command, and follow the instructions:

docker login

Now images can be pulled automatically with “docker compose”. Or manually saved to disk if needed in an offline environment.

(Optional) How to save images to an offline environment

From inside the unzipped MAL_* folder, where the docker-compose.yml file is placed.

First, pull all images:

docker compose pull

Then save all images pulled to tar files with:

docker save imagename -o image.tar

Move all files to the offline environment and import them with:

docker load -i image.tar

Run

1. Extract content from the asta7-* zip file and navigate inside.

2. Open the .env file, and edit the variable COMPOSE_PROJECT_NAME to the preferred name. Or leave at asta7.

3. Run docker compose up -d in the terminal to start the project. This will create and start the necessary containers to run the archive manager. The '-d' flag indicates the detached mode.

   docker compose up -d

The started services can be viewed by running

docker compose ps

The initialization process might take a minute or two to finish when ready visit http://localhost

For more details on what goes on in the initial process run docker compose logs or docker compose logs -f (follow/trace logs).

Ports

In case Asta7 is running under a firewall you need to open port 80 for HTTP and port 443 for HTTPS.

Repository

For running, repository containers change COMPOSE_PROFILES in the .env file.

COMPOSE_PROFILES=repository

Change REPOSITORY_URL in the .env file. For example

REPOSITORY_URL=http://localhost/repository

Multiple profiles can be added using comma(,) as the separator

COMPOSE_PROFILES=repository,requisition

Requisition

For running, repository containers change COMPOSE_PROFILES in the .env file.

COMPOSE_PROFILES=requisition

Persisting ENV

Unless this is a test environment, some of the values (ASTA7_URL, COMPOSE_PROFILES, etc.) in the .env file need to be changed. Keeping these changes intact after every upgrade becomes a hassle. With the help of COMPOSE_ENV_FILES we can make things easier. Follow the below steps

1. Create an additional env file in a suitable location with the environment variables that you want to change or add. For example here is an env file in the home directory (/home/ubuntu/.env.asta7) and its content

   COMPOSE_PROFILES=requisition,repository
   ASTA7_URL=https://prototype.stiftelsen-asta.no
   REQUISITION_URL=https://prototype.stiftelsen-asta.no/requisition/
   REPOSITORY_URL=https://prototype.stiftelsen-asta.no/repository/
   KEYCLOAK_AM_CORE_SECURITY_CREDENTIALS=077a06da-26e7-4364-abdd-1f6aa0f717bb
   ESSYNC_CLIENT_SECRET=b0d32b35-aaa9-4d02-866d-5d6aaafb3bb9
   REQUISITION_CLIENT_SECRET=08b8b4a4-c219-40bd-837b-7ba95cfbc96c
   REPOSITORY_CLIENT_SECRET=631819cf-329d-4d74-a765-130a64134068

2. Add an entry to the /etc/environment file

   COMPOSE_ENV_FILES='.env,/home/ubuntu/.env.asta7'

3. Now exit the shell and enter again, that’s it the Asta7 should now keep your environment variable changes.

Security configuration

You now have a working solution, with the basic configuration. The basic configuration will only work on localhost, to add additional accepted addresses it must be configured. To add additional addresses follow the below procedure. Both ‘client' and ‘core’ need the same change.

Go to the administration GUI of Keycloak our security solution on http://localhost:8081/auth/admin/ or simply use the link provided in Asta7.

Here you can log in with the default admin user. After logging in first change the realm from master to archive-manager

Now select Clients from the left-hand menu. On the resulting page, you will see all the clients in use as exemplified below.

Click client and scroll down to Valid Redirect URIs and Web Origins. Add http://target_host/* in Valid Redirect URIs and http://target_host in Web Origins.

Repeat the same in the core client as well.

Setup administrator email and password reset feature for users

To enable user password reset you will need to enable forgot password option in realm login settings.

In the Keycloak admin console go to Realm Setting > Login and enable forgot password feature.

Next, you need to set up your email for Keycloak admin.

For this first, ensure that the admin has an email address associated with the account. Go to Manage account > personal info from the admin dashboard and set your admin email.

Next, set up an email service for Keycloak by going to Realm Settings > Email > Connection & Authentication. Make sure to use the administrator email that was set in the previous step.

The email settings may vary based on the email service provider. A sample setting for Gmail is given below:

Note that you may need to set up authentication passwords, or configure security settings on the email account you may be using.

Afterward, make sure that the user requesting a password reset has an associated email account.

Go to Users from the Keycloak admin dashboard and select the user.

Now the user will be able to reset his/her password from the Asta 7 login page by clicking forgot password and entering their username/email.

Rotate The Keys

You need to rotate/regenerate the public keys used to sign the tokens. In the Keycloak admin console go to Realm settings > Keys > Providers. Then click the Add provider button

Add provider for aes-generated, res-generated, and hmac-generated. At last, delete the old providers.

Extended session time setup

In the Keycloak admin console go to Realm settings > Sessions and change the marked field to set up extended session idel and session max time limit.

Set Realm Display Name

If you want to show a custom name on your Google authenticator or Free OTP app then follow the below step.

Go to Realm Settings > General > Display name. Set Asta 7 as the display name and click the Save button. Next time, your provided Display name will be shown on Google Authenticator or the Free OTP app.

OTP/Two-Factor Authentication

ON

In the Keycloak admin console go to Authentication > Flows, then select the browser flow

Change the value for Browser - Conditional OTP to Required

Then log in to Asta7 and scan the QR code using Google Authenticator or Free OTP app or enter the key in Google Authenticator or Free OTP app, after completing log in with username and password.

After scanning put the OTP from the app and submit first time.

The next time you need to put OTP from the authenticator application

OFF

Set the value for Browser - Conditional OTP to Disabled

Change User Credentials

If needed change the sys_admin user credential by going to Users from the left menu. Then open the sys_admin user edit form and go to the Credentials tab. Here click the Reset password button for Password

Put your desired password there and make sure to uncheck the Temporary option before resetting.

HTTPS Configuration

For HTTPS one of the following options can be used

No HTTPS

By default there is no HTTPS configuration present, so the solution will work without any further changes. But there is a catch here: it will only work for localhost or private IP addresses.

In order to make it work for all external hosts, you have to change a configuration in Keycloak. Go to Realm Settings from the left-hand menu under Configure. Now open the General tab and change the Require SSL configuration to none. You have to make this change for both the Archive-manager and the Master realm.

Direct HTTPS

If you have SSL/TLS certificates and you want Asta7 to use them go through the following steps in the host machine running the Asta7 docker

1. Create a directory with the name .asta7-ssl in the home directory of the user running the docker process. In Linux/Mac the location should be /home/<username>/.asta7-ssl and in Windows, it should be C:\Users\<username>\.asta7-ssl. If the root user is running the docker in Linux/Mac then the location of the directory should be /root/.asta7-ssl.

2. Put the public-key certificate file (in case of a chained certificate this should be the fullchain file containing all the certificates) in the .asta7-ssl directory with the name certificate.actual_extension. For example, if the certificate file name is fullchain.pem then put it with the name certificate.pem.

3. Put the private-key certificate file in the .asta7-ssl directory with the name certificate_key.actual_extension. For example, if the certificate file name is privkey.pem then put it with the name certificate_key.pem.

4. Put the dh-parameters file in the .asta7-ssl directory with the name dhparam.actual_extension. For example, if the certificate file name is dhparam.pem then put it with the same name. The dh-parameters can be generated using the openssl tool. The following command can be used to generate a new set of 2048-bit dh-parameters

   openssl dhparam -out ~/.asta-ssl/dhparam.pem 2048

5. To change the ownership of the .asta7-ssl folder to the currently logged-in user, run the following chown command:

   sudo chown -R $USER:$USER ~/.asta7-ssl

   This command will recursively change the ownership of the folder and all its contents to match the logged-in user and their group. Remember to use sudo to execute the command as the superuser .

Letsencrypt

If you want to use Letsencrypt for obtaining the certificate you can use the Standalone or the DNS plugins of Certbot for generating certificates.

Letencrypt’s certificates are valid for 90 days. When the certificates are renewed, they have to be copied to the .asta7-ssl and the asta7 Nginx service needs to be reloaded if running. In Linux, the following script can be used to achieve that.

cp /etc/letsencrypt/live/your.host.name/fullchain.pem ~/.asta7-ssl/certificate.pem
cp /etc/letsencrypt/live/your.host.name/privkey.pem ~/.asta7-ssl/certificate_key.pem
docker exec gui-pt nginx -s reload

HTTPS Using A Load Balancer/Reverse Proxy Server

If you have a load balancer or reverse proxy server configured for HTTPS and want to serve Asta7 using it just pass all the requests to port 80 of the Asta7 host machine. Also, make sure that the X-Forwarded-Proto header is being appropriately set while passing requests to Asta7. Here is a sample Nginx configuration

map $http_x_forwarded_proto $proxy_scheme {
    default $scheme;
    http http;
    https https;
}

server {
    listen 80;
    listen [::]:80;
    server_name domain_name;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name domain_name;
    
    ssl_certificate /path/to/certificate_file;
    ssl_certificate_key /path/to/private_key_file;
    
    proxy_buffer_size 64k;
    proxy_buffers 8 64k;
    proxy_busy_buffers_size 64k;
    large_client_header_buffers 4 64k;
    client_max_body_size 0;

    location / {    
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_request_buffering off;

        proxy_read_timeout 1d;
        proxy_connect_timeout 1d;
        proxy_send_timeout 1d;
        
        proxy_set_header Host $host;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $proxy_scheme;
        proxy_pass_request_headers on;
        
        proxy_pass http://proxy_ip_or_domain;
     }
}

Upgrade

Stop Running Asta7

If you already have Asta7 running make sure to stop them.

docker compose stop

In case of updating to a significantly newer version, it is recommended to use the following

docker compose down

Update and Run

Unzip the package and get into the unzipped directory.

unzip asta7-1.22.0.zip
cd asta7-1.22.0

Now run the following commands to update and run the package

docker compose up -d

Remove Old Directory

If deployment was successful delete the old package and directory.

rm -r asta7-old_version

Add syndication URL for publishing to the portal

Admin needs to provide the syndication_url to the .env file. Then the user will be able to get the option for publishing the archive to the portal.

Add nginx custom log to Data Disk

To store user-related logs and API calls, we'll set up a Docker Compose volume. This links NGINX container logs to a designated folder on our data disk. This allows easy access and management of logs for debugging and analysis.

1. create asta7_nginx_log folder in /data folder and change the ownership from root to user

sudo chown -R $(whoami):$(whoami) /data/asta7_nginx_log

2. add a new docker host bind mount to store the log

volumes:
      - ~/.asta7-ssl:/etc/nginx/ssl
      - /data/asta7_nginx_log:/var/log/nginx

3. Need to rotate the log in the host machine

sudo apt install logrotate
sudo nano /etc/logrotate.d/asta7

/data/asta7_nginx_log/*.log {
        weekly
        compress
        create 0640 ubuntu ubuntu
        copytruncate
        dateext
        su root adm
        missingok
        notifempty
}

# to spot our logrotate configuration
sudo logrotate /etc/logrotate.conf --debug

# to Test without waiting
sudo logrotate -f /etc/logrotate.d/asta7

# in the "/data/asta7_nginx_log/" we will find backup file of the log and original file become empty

Enable Azure Blob Storage Support

Basic Setup and Configuration

To enable Azure blob storage support, we first need an Azure account and retrieve the following credentials from the account:

Azure Account Name
Azure Account Key
Azure Blob Storage Endpoint

Alternatively, for local development use, we can use Azurite docker image. Set the following properties in the .env file

AZURE_STORAGE_ACCOUNT_NAME=devstoreaccount1
AZURE_STORAGE_ACCOUNT_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
AZURE_BLOB_ENDPOINT=http://azurite:10000/devstoreaccount1/

Additionally, for Azurite we need to set the following property in the .env file

COMPOSE_PROFILES=azurite

Finally, to enable Azure we need to set the following property in .env

AZURE_BLOB_ENABLED=true

Determining the Blob Storage Endpoint from the Connection String

Sometimes instead of getting a blob endpoint, we may get a connection string instead. Here is a sample of a connection string:

DefaultEndpointsProtocol=https;AccountName=storagesample;AccountKey=<account-key>EndpointSuffix=core.windows.net

A blob endpoint based on this connection string may look like this

BlobEndpoint=https://storagesample.blob.core.windows.net

Using Azure Storage Explorer to validate

After the setup, Azure Blob storage will be functional. To verify and explore the Azure blob storage, we can setup and use

Azure Storage Explorer

For Azurite we should use the local storage emulator option, for Azure, we can use the connect to Azure storage option.

For both cases we will need the account name, account key, and endpoint/connection string we discussed above.