Guide for deploying new versions on decentral

server in production version 2.1

This guide outlines the steps for deploying new versions of the application in production,
applicable to both municipal installations and court systems (TPE). The application consists
of a decentralized backend built with Java Spring and a frontend built with Angular. The
backend application is launched as a .jar file, and the frontend application is updated in the
Nginx folder.

Table of Contents
1. Preparation...........................................................................................................................1
2. Deploying the Backend Application......................................................................................2
3. Deploying the Frontend Application.....................................................................................5
4. Post-Deployment Tasks.......................................................................................................5
5. Back-out Plan.......................................................................................................................6
Description of Standard Spring Boot Properties.......................................................................7
Creating an Admin User...........................................................................................................8

Introduction of installation guide 2.0

Installation guide 2.0 has been released due to the following changes:
1. Transition to Flyway for Database Updates: The process for updating the database has
been streamlined and simplified with the use of Flyway. This tool provides structured
management of database schemas, making updates easier to implement and ensuring
consistency across deployments.

2. New Extract URL Setting: A new configuration has been introduced for the extract URL.
This requires specific instructions to ensure the URL is set correctly, which is crucial for
accurate data retrieval.

These updates make the installation instructions clearer and facilitate a smoother installation
process, aligned with the new functionalities and technologies.

1. Preparation
Backup:

Guide for deploying new versions on decentral server in production

1
Ensure a complete backup of the current production environment, including the following
components:

The current backend application (.jar file): Copy the existing .jar file to a secure location.

Configuration files: Backup all relevant configuration files, such

as application.properties and config.json.

Communication:
Inform all stakeholders about the planned deployment, including potential downtime.

≠2. Deploying the Backend Application

1. Stopping the current backend:
o Stop the current version of the backend application to prevent conflicts.
2. Backup of the current application and configuration:
o Application: Ensure the current .jar file is securely copied to a backup
location.
o Configuration: Backup the current application.properties file and other
configuration files in use.
3. Updating the backend:
o Replace the old .jar file with the new version in the production environment.
4. Checking and updating configuration:
o Review the application.properties file. The configuration should contain the
correct values for the production environment, such as URLs, usernames,
passwords, and other settings.
Key adjustments for different installations:
o Municipal installation:
 court.code should be set to 000.
 nis.code should match the municipality_id code of the municipality
from the code_municipality table.
o Court (TPE) installation:
 court.code should match the court's code from the code_court table.
 nis.code should be set to 00000.
Flyway Settings:
o Flyway settings should be configured only once during initial setup and do not
need to be changed with every deployment.
o For new installations:
spring.flyway.baseline-on-migrate=false

Guide for deploying new versions on decentral server in production

2
 spring.flyway.locations=classpath:db/migration
o For existing installations:
spring.flyway.baseline-on-migrate=true
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-version=1
Specific settings descriptions:
o gn.gov.etatcivil.services.extracts.server.url: This is the URL to the
extract service, used for retrieving extracts.
o gn.gov.etatcivil.etatcivilcore.url: This is the URL to the central server,
serving as the main system for communication and data management.

Example configuration:
# DataSource Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/dbdecentral
spring.datasource.username=gnetatcivil
spring.datasource.password=xxxxxxxx
spring.jpa.show-sql=false
logging.file.name=/opt/etatcivil/decentral/logs/decentral_server.log

# Flyway settings (see above for specific configurations)

spring.flyway.baseline-on-migrate=false
spring.flyway.locations=classpath:db/migration

## Hibernate Properties
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.properties.hibernate.format_sql=false
spring.jpa.hibernate.ddl-auto=none

# Logging configuration
logging.level.org.hibernate.type=WARN
logging.level.org.hibernate.SQL=ERROR

Guide for deploying new versions on decentral server in production

3
logging.level.org.springframework=WARN
logging.level.gn.gov.etatcivil=DEBUG

# Server configuration
server.port=8090

# Configuration for connection to central server

gn.gov.etatcivil.etatcivilcore.url=https://test.e-renec.gov.gn:8080
gn.gov.etatcivil.service.token.issuer=GN
gn.gov.etatcivil.service.token.key=d87A7741B65Cc1342Fba25456aC48
gn.gov.etatcivil.service.token.validityInSeconds=86400

# Synchronization job planning

gn.gov.etatcivil.services.code.job.interval=0/20 * * * * ?
gn.gov.etatcivil.services.migration.job.interval=0 */30 * ? * *
gn.gov.etatcivil.services.attachemts.job.interval=0 */10 * ? * *
gn.gov.etatcivil.services.notifications.job.interval=0 */5 * ? * *

jasypt.password=dav-asa-dabs-4u

# Code of the commune or court

nis.code=00003 # Example for municipality
court.code=036 # Example for court

spring.mvc.pathmatch.matching-strategy=ant_path_matcher
# Configuration URL extract central service
gn.gov.etatcivil.services.extracts.server.url=https://test.e-renec.gov.gn:8080/extract/

# SSL configuration
security.require-ssl=true
server.ssl.key-store=/etc/letsencrypt/live/test.e-renec.gov.gn/keystore.p12
server.ssl.key-store-password=xxcxxxxx
server.ssl.keyStoreType=PKCS12
server.ssl.keyAlias=tomcat

Guide for deploying new versions on decentral server in production

4
 5. Starting the backend application:
o Start the new version of the backend application and verify its proper
functionality.
6. Checking log files:
o Review the log files (/opt/etatcivil/decentral/logs/decentral_server.log) for any
errors or issues during startup.

3. Deploying the Frontend Application

1. Backup of the current frontend:
o Backup the current Angular frontend files in the Nginx directory.
2. Updating the frontend:
o Copy the new version of the Angular frontend files to the Nginx directory.
3. Configuring frontend:
o Check and update the configuration in the config/config.json file. The
configuration should include the following properties:
json
{
"linkCentral": "https://test.e-renec.gov.gn:8080",
"linkDecentral": "https://test.e-renec.gov.gn:8090",
"linkFront": "https://test.e-renec.gov.gn",
"headerTop": "HEADER_TITLE_LAND",
"headerMiddle": "HEADER_TITLE_MINISTRY",
"headerBottom": "HEADER_TITLE_REGISTRY"
}
 linkCentral: URL to the central services.
 linkDecentral: URL for the decentralized services.
 linkFront: Browser URL where the application is accessible.
 headerTop, headerMiddle, headerBottom: Configuration for the
header text in the application.
4. Verifying the frontend:
Ensure that the frontend displays and functions correctly in the production
environment.

4. Post-Deployment Tasks
1. Checking Code Tables:

Guide for deploying new versions on decentral server in production

5
 o Ensure that the following code tables are correctly populated and updated:
 code_country
 code_location
 code_profession
 code_prefecture
 code_municipality
 code_district_quartier
 code_secteur
 code_parental_link
 code_instruction_level
 code_court
 abs_table
 code_attachment_type
 top_firstnames
 top_names
 code_special_disposition
 code_reverse_parental_link
o Review the code_version table to ensure that a publication_ts (publication
timestamp) is set for each of the above tables. This process may take
approximately 30 minutes and is crucial to ensure all tables are up-to-date
and correctly synchronized with central data.

2. Clearing Local Cache on Workstations: After the installation, clear the local cache
on all workstations to prevent issues with lingering elements from the old version of
the application. This step ensures that all users have access to the latest updates
and that no outdated files cause conflicts or errors.

3. Performing tests:
o Conduct a series of tests to verify that the new versions are functioning
correctly, including functional and regression tests.
4. Monitoring:
o Closely monitor the application for any issues or performance fluctuations.
5. Communicating completion:
o Inform all stakeholders that the deployment has been successfully completed
and provide a brief summary of the changes.

Guide for deploying new versions on decentral server in production

6
5. Back-out Plan
1. Reverting to the previous version:
o If necessary, prepare a plan to revert to the previous version of the backend
and/or frontend. This includes restarting the old version.
2. Communication:
o Inform stakeholders about the rollback and the reasons for it.

Description of Standard Spring Boot Properties

Below is a brief description of the standard Spring Boot properties that can be configured in
the application.properties file:
 spring.datasource.url: The JDBC URL for database access.
 spring.datasource.username: The username for database access.
 spring.datasource.password: The password for database access.
 spring.jpa.show-sql: Determines whether SQL statements are displayed in the logs
(true/false).
 spring.jpa.hibernate.ddl-auto: Specifies how Hibernate manages database
schemas (create, create-drop, validate, update, none).
 logging.file.name: The path to the log file where log information is stored.
 logging.level.*: Sets the log level for various components (e.g., ERROR, WARN,
INFO, DEBUG).

Following these steps and configurations will help ensure a smooth deployment of new
versions without major disruptions. Ensure that all steps are carefully executed and maintain
good communication with all stakeholders.

Guide for Creating an Admin User for New Installations

This guide explains how to create an admin user for a municipality, consulate, or court
during the setup of a new application. It includes details on user creation, role assignment,
and how password expiration is managed. It also covers the decentralized nature of user
management and central synchronization when the system is online.

Overview
To create an admin user in the system, you need to:

 Insert a record into the users table, which stores user information.
 Insert a corresponding record into the user_roles table, which assigns the user a role (e.g., admin
for a municipality, consulate, or court).

Guide for deploying new versions on decentral server in production

7
 Ensure the password is securely hashed, and the updated_password_date is tracked to enforce
password expiration policies.

Key Concepts

Decentralized Creation: Admin users are created locally at each municipality, consulate, or
court.
Central Synchronization: When the central system is available, user accounts are
synchronized with the central database during login.
Password Expiration: Passwords are checked against the updated_password_date field to
determine if they have expired, based on the system’s security policy.

Creating an Admin User

Step 1: Create a User in the users Table

The user is created by inserting a new record into the users table. The user_id is generated
from a sequence (user_sequence), ensuring it’s unique. The working_place_code field
identifies the user's place of work (municipality, consulate, or court). The password is stored
as a hashed value.

Below is a sample SQL script for creating an admin user for each type of workplace:

Example for a Municipality Admin (e.g., Matoto)

DO $$
DECLARE
new_user_id bigint;
BEGIN
-- Generate a new user_id from the user_sequence
new_user_id := nextval('user_sequence');

-- Insert the new user into the users table

INSERT INTO users (id, comment, deleted, enabled, external_id, firstnames, lastname,
updated_password_date, password, username, working_place_code, last_update_time)

Guide for deploying new versions on decentral server in production

8
 VALUES (new_user_id, 'Admin for Matoto Municipality', false, true, 'EXT123456', 'Admin',
'Matoto', NOW(), 'T53dw7UOfNbpovKFex9/Ldz8CMUF95gD', 'admin.matoto', '00003',
NOW());

-- Insert the corresponding role into the user_roles table

INSERT INTO user_roles (user_id, role)
VALUES (new_user_id, 2); -- Role ID for a municipality admin
END $$;

Example for a Consulate Admin (e.g., Consulat à Paris)

DO $$
DECLARE
new_user_id bigint;
BEGIN
-- Generate a new user_id from the user_sequence
new_user_id := nextval('user_sequence');

-- Insert the new user into the users table

INSERT INTO users (id, comment, deleted, enabled, external_id, firstnames, lastname,
updated_password_date, password, username, working_place_code, last_update_time)
VALUES (new_user_id, 'Admin for Consulat à Paris', false, true, 'EXT654321', 'Admin',
'Consulat', NOW(), 'T53dw7UOfNbpovKFex9/Ldz8CMUF95gD', 'admin.paris', 'C1111',
NOW());

-- Insert the corresponding role into the user_roles table

INSERT INTO user_roles (user_id, role)
VALUES (new_user_id, 9); -- Role ID for a consulate admin
END $$;

Example for a Court Admin (e.g., TPI de Kindia)

DO $$
DECLARE
new_user_id bigint;
BEGIN
-- Generate a new user_id from the user_sequence

Guide for deploying new versions on decentral server in production

9
 new_user_id := nextval('user_sequence');

-- Insert the new user into the users table

INSERT INTO users (id, comment, deleted, enabled, external_id, firstnames, lastname,
updated_password_date, password, username, working_place_code, last_update_time)
VALUES (new_user_id, 'Admin for TPI de Kindia', false, true, 'EXT789012', 'Admin',
'Kindia', NOW(), 'T53dw7UOfNbpovKFex9/Ldz8CMUF95gD', 'admin.kindia', 'J016', NOW());

-- Insert the corresponding role into the user_roles table

INSERT INTO user_roles (user_id, role)
VALUES (new_user_id, 8); -- Role ID for a court admin
END $$;

Explanation of Columns
Table: users
 id: A unique identifier generated by the user_sequence. It is the primary key of the table.
 comment: Optional notes or comments about the user (e.g., their role or specific details
about their function).
 deleted: Indicates whether the user is deleted. Set to false for active users.
 enabled: Indicates if the user is active. Set to true for users who are allowed to log in.
 external_id: External reference ID, such as one used by another system.
 firstnames: The first names of the user.
 lastname: The last name of the user.
 updated_password_date: Tracks the last time the password was updated. This is used to
enforce password expiration rules.
 password: The hashed password of the user. In this example, NewPass2024!-! is hashed
as T53dw7UOfNbpovKFex9/Ldz8CMUF95gD.
 username: The unique login name for the user.
 working_place_code: Identifies the user's workplace:
– '00003' for Matoto Municipality.
– 'C1111' for Consulat à Paris.
– 'J016' for TPI de Kindia.
 last_update_time: The timestamp of the last update to this user's record.

Guide for deploying new versions on decentral server in production

10
Table: user_roles
 user_id: References the id field in the users table, linking the user to their role.
 role: The ID of the role assigned to the user. For example:
– 2 for a municipality admin.
– 9 for a consulate admin.
– 8 for a court admin.

Password Expiration
The updated_password_date column is used to track when the user last updated their
password. If the system enforces password expiration policies (e.g., a password must be
changed every 90 days), this field is checked during login to determine whether the user
needs to change their password.

Decentralized User Creation and Central Synchronization

This system allows for decentralized user creation, meaning each municipality, consulate, or
court can independently create and manage their own users. This provides flexibility and
autonomy to local administrators.

When a user logs in, if the central system is online, the user account is synchronized with
the central database. This process ensures that all users are unified and centralized,
allowing for consistent user management across all systems.

Example Scenario

An admin for the Matoto Municipality can be created locally using the SQL script shown
earlier. When this user logs into the central system (if it is available), their information is
synchronized with the central database. This ensures consistent and up-to-date user data
across both local and central systems.

Key Points
 Local Admin Creation: Admin users are created locally at each workplace (municipality,
consulate, or court).
 Central Synchronization: When the central system is available, users are synced to the
central database upon login.
 Password Expiration Enforcement: The system checks the updated_password_date
field to determine if a password change is required based on expiration policies.
This guide provides a step-by-step process for creating admin users at the local level while
ensuring that centralized user management and security policies are enforced when
necessary.

Guide for deploying new versions on decentral server in production

11
Guide for deploying new versions on decentral server in production
12