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

Image Added

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

Image Removed

Image Added

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.

Image Removed

Image Added

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.

Image Added

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.

Image Added

Image Added

Image Added

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:

Image Added

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.

Image Added

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.

Image Added

Image Added

Rotate The Keys

You need to rotate/regenerate the public keys used to sign the tokens. Login to keycloak In the Keycloak admin console then go to Realm Settings settings > Keys > Providers.

Image Removed

Click Add keystore and add a aes-generated keystone with a suitable name

Image Removed

Repeat the process for res-generated Then click the Add provider button

Image Added

Add provider for aes-generated, res-generated, and hmac-generated as well. 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.

Image Added

Go to Realm settings > Tokens and change the token lifetime.

Image Added

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.

Image Added

OTP/Two-Factor Authentication

ON

Select required for “Browser - Conditional OTP”

Image Removed

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

Image Added

Change the value for Browser - Conditional OTP to Required

Image Added

Then log in to Asta7 and scan the QR code by Google authenticator 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.

Image Removed

Image Added

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

Image Removed

Image Added

OFF

Select disabled for “Browser Set the value for Browser - Conditional OTP”OTP to Disabled

Image Removed

Change User Credentials

If needed change the sys_admin user credential by going to Users from the left menu, then click the View all users button from the top menu. Then open the sys_admin user edit form and go to the Credentials tab.

Image Removed

Here click the Reset password button for Password

Image Added

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 that : 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 Login General tab and change the Require SSL configuration to none. You have to do make this change for both the Archive-manager and the Master realm.

Image Removed

Image Removed

Image Added

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-compose

1. Create a directory with the name .asta7-ssl in the home directory of the user running the docker

1. 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

1. in Linux/Mac then the location of the directory should be /root/.asta7-ssl.

2. Put the public-key certificate file (in case of

1. 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.

2. 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.

3. Put the

1. 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

1. dh-parameters can be generated using the openssl tool. The following command can be used to generate a new set of 2048-bit

1. dh-parameters

   Code Block
   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:

   Code Block
   language bash
   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 properly 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 docker-compose downthe 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 --build

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 .envfile. 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.