paradigmasoft/valentina-server repository overview

⁠What is Valentina Server?

Valentina Server (sometimes referred to as VServer) is a complete server platform that includes multiple servers and provides a variety of services.

When it was first released, Valentina Server acted primarily as a multi-user environment for Paradigma Software's Valentina DB⁠ object-relational database. Since then, Valentina Server has expanded to include additional servers and capabilities, such as:

• Valentina DB Server – manages Valentina database files, providing multi-user access to stored data.
• Valentina SQLite Server – manages SQLite database files, providing multi-user access to stored data. Learn more⁠.
• Valentina DuckDB Server – manages DuckDB database files, providing multi-user access to stored data.
• Valentina Reports Server – provides multi-user access to the Valentina Reports Engine⁠. Reports can use Valentina, SQLite, DuckDB, MySQL, PostgreSQL, ODBC, and SQL Server databases as data sources. A report can be exported to multiple formats (PDF, HTML, ODT, image) or sent directly to a printer.
• Valentina Forms Server – provides multi-user access to form objects stored within Valentina project files.

⁠Supported Architectures

The Docker image is available for the following architectures:

• 64-bit Linux
• 32-bit ARM Linux
• 64-bit ARM Linux

These images are combined into a single multi-architecture image. Docker automatically selects the correct architecture unless the user specifies one explicitly.

You can use this image on macOS, Linux and Windows systems.

⁠Additional Resources

For more information and related downloads for Valentina Server and other Paradigma Software products, please visit:
http://www.valentina-db.com⁠

It is also recommended to download Valentina Studio⁠, a desktop application for managing databases, tables, fields, stored procedures, as well as designing reports and forms.

⁠How to use this image

Make sure Docker is installed on your system before using these images.

⁠Start the Valentina Server instance

By default, Valentina Server listens for connections on the following ports:

• 15432 - Valentina
• 15434 - Valentina SSL
• 15532 - SQLite
• 15534 - SQLite SSL
• 15632 - DuckDB
• 15634 - DuckDB SSL

To connect from outside the container, you need to publish these ports by passing the appropriate -p arguments to the docker run command.

Starting the Valentina Server instance:

$ docker run --name some-vserver -d \
    -p 25432:15432 \
    -p 25434:15434 \
    -p 25532:15532 \
    -p 25534:15534 \
    -p 25632:15632 \
    -p 25634:15634 \
paradigmasoft/valentina-server

... where some-vserver is the name you want to assign to your container.

With this explicit mapping, you can now connect to the server using these ports (25432, 25434, 25532, 25534, 25632, 25634).

The Valentina Server image will be automatically pulled from the Docker Hub repository.

Note: on Windows, in the PowerShell terminal, newline characters are handled differently. The command should look like this:

$ docker run --name some-vserver -d `
    -p 25432:15432 `
    -p 25434:15434 `
    -p 25532:15532 `
    -p 25534:15534 `
    -p 25632:15632 `
    -p 25634:15634 `
paradigmasoft/valentina-server

Alternatively, you can use the Docker Desktop⁠ application to create and manage your containers visually.

⁠Connect to Valentina Server from Valentina Studio

Click the Connect to... button on the start page, select Valentina Server, and enter the following parameters:

• host = 127.0.0.1 or localhost
• port = <port mapped to 15432>
• user = sa
• password = sa

Make sure to uncheck the Use Notifications option, as it requires a few extra steps⁠.

To connect to Valentina SQLite Server, select SQLite Server as the target and enter the following parameters:

• host = 127.0.0.1 or localhost
• port = <port mapped to 15532>
• user = sa
• password = sa

⁠Adding a License

Without a license, Valentina Server allows only one simultaneous connection.
You can obtain a FREE license that provides:

• 5 Valentina DB connections
• 5 DuckDB connections
• 10 SQLite connections
• 10 REST connections

Alternatively, you can purchase a license with more connections from the Paradigma Store⁠.

For more details, see the Licenses documentation⁠.

⁠License File Formats

The license filename can use the following formats:

• For Linux OS – license_lin_dddddd
• Universal embedded – license_emb_dddddd

⁠Default License Location

By default, licenses are stored in the following container folder: /opt/VServer/licenses

This location can be changed using the LicenseCatalog option in the INI file.

⁠Ways to Provide a License

Once you have received your license file, you can pass it to Valentina Server in one of the following ways:

• Mount the licenses folder from the host system
• Upload the license using Valentina Studio
• Copy the license to the container using the docker cp command

After the server starts, the license will be applied automatically.

⁠Mount the Licenses Folder

Download your license to an empty folder on your host system (e.g., /VSERVER_DATA/licenses).

You can mount this folder to the container's licenses folder:

$ docker run --name some-vserver -d \
    --mount type=bind,source=/VSERVER_DATA/licenses,target=/opt/VServer/licenses \
    paradigmasoft/valentina-server

Alternatively, you can mount an individual license file:

$ docker run --name some-vserver -d \
    --mount type=bind,source=/VSERVER_DATA/licenses/license_lin_dddddd,target=/opt/VServer/licenses/license_lin_dddddd \
    paradigmasoft/valentina-server

This method is recommended for production environments, as it simplifies updating containers while keeping licenses on the host system.

Note: On macOS, you must share⁠ the folder you mount.

⁠Upload the License Using Valentina Studio

Connect to Valentina Server.

There are three ways to upload a license:

1. Drag and drop the license file onto the server connection.

2. Context menu: Right-click the connection, select Upload License..., and choose the license file.

1. Server Admin: Open Server Admin⁠ from the Tools submenu in the application main menu, switch to the Licenses tab, and use the Upload... button to select the license file, or drag the license file to the list.

⁠Copy the License to the Container

A license can be added easily using the docker cp command.
Navigate to the directory containing the license on your host system and execute:

$ docker cp license_lin_dddddd some_vserver:/opt/VServer/licenses

Make sure to restart the container after adding a license.

⁠Using the Valentina Server Configuration File

Valentina Server configuration is defined in an INI file.
By default, it is stored in the container at:

/opt/VServer/vserver.ini

You may need to adjust this configuration to suit your needs, for example, to enable the REST interface.

⁠Ways to Modify the INI File

• Manually using a text editor.
• Using Valentina Studio – in the properties of the connection or via Server Admin.
• Using Valentina ADK – with an SQL query or API call.
• Executing an SQL query via the Valentina Server REST interface.

⁠Mounting a Custom INI File from the Host

Like licenses, you can mount your INI file from the host system.
Place your adjusted configuration in /VSERVER_DATA and run:

$ docker run -d --name some-vserver \
    -p 25432:15432 \
    -p 25532:15532 \
    --mount type=bind,source=/VSERVER_DATA/vserver.ini,target=/opt/VServer/vserver.ini \
    paradigmasoft/valentina-server

This method simplifies upgrades and configuration management.

Note: On macOS, it is necessary to share⁠ the folder containing the mounted file.

⁠Enabling Notifications

The Notifications⁠ mechanism in Valentina Server allows subscribed clients to send and receive text messages. Messages are delivered to all clients subscribed to a specific notification channel. Additionally, the server sends notifications about schema changes.

By default, notifications are disabled. To enable them, assign a value to the Port_NOTIFICATION option in the INI file:

Port_NOTIFICATION=25436

Alternatively, you can execute an SQL query (for example, in the SQL Editor of Valentina Studio):

SET PROPERTY "PORT_NOTIFICATION" OF SERVER TO 25436

After restarting the container, the new value will be applied.

You can then publish and map the notifications port:

$ docker run --name some-vserver -d \
    -p 25432:15432 \
    -p 25436:25436 \
    paradigmasoft/valentina-server

To use notifications in Valentina Studio, map the same port as specified in the configuration (-p 25436:25436) and enable the Use Notifications option when connecting.

⁠Where to Store Valentina Server Data

By default, Valentina Server data (databases, projects, licenses, configuration) is stored inside the container. While this is transparent to the user, it can make accessing files from host tools and applications difficult and complicates upgrades between container versions.

A better approach is to create a data directory on the host system and mount it into the container. This ensures database files and projects are in a known location on the host, simplifying access and upgrades. You must ensure the directory exists and that permissions and security settings are configured properly.

⁠Default Folders in the Container

• /opt/VServer/databases
• /opt/VServer/sqlite_databases
• /opt/VServer/projects

⁠Example Host Directories

• /VSERVER_DATA/databases
• /VSERVER_DATA/sqlite_databases
• /VSERVER_DATA/projects

⁠Starting the Container with Mounted Data

Basic mount:

$ docker run -d --name some-vserver \
    -p 25432:15432 \
    -p 25532:15532 \
    --mount type=bind,source=/VSERVER_DATA/databases,target=/opt/VServer/databases \
    --mount type=bind,source=/VSERVER_DATA/projects,target=/opt/VServer/projects \
    --mount type=bind,source=/VSERVER_DATA/sqlite_databases,target=/opt/VServer/sqlite_databases \
    paradigmasoft/valentina-server

With licenses outside the container:

$ docker run -d --name some-vserver \
    -p 25432:15432 \
    -p 25532:15532 \
    --mount type=bind,source=/VSERVER_DATA/licenses,target=/opt/VServer/licenses \
    --mount type=bind,source=/VSERVER_DATA/databases,target=/opt/VServer/databases \
    --mount type=bind,source=/VSERVER_DATA/projects,target=/opt/VServer/projects \
    --mount type=bind,source=/VSERVER_DATA/sqlite_databases,target=/opt/VServer/sqlite_databases \
    paradigmasoft/valentina-server

With the INI file stored on the host:

$ docker run -d --name some-vserver \
    -p 25432:15432 \
    -p 25532:15532 \
    --mount type=bind,source=/VSERVER_DATA/vserver.ini,target=/opt/VServer/vserver.ini \
    --mount type=bind,source=/VSERVER_DATA/licenses,target=/opt/VServer/licenses \
    --mount type=bind,source=/VSERVER_DATA/databases,target=/opt/VServer/databases \
    --mount type=bind,source=/VSERVER_DATA/projects,target=/opt/VServer/projects \
    --mount type=bind,source=/VSERVER_DATA/sqlite_databases,target=/opt/VServer/sqlite_databases \
    paradigmasoft/valentina-server

With this setup, upgrading the server is as simple as removing the old container and creating a new one.

⁠Mounting on macOS

On macOS, any folder mounted into the Docker container must be shared.

Go to Docker Desktop Menu > Preferences > File Sharing and add the folder you want to share:

All subdirectories of a shared folder are shared automatically.

⁠Connect to Valentina Server from the Valentina ADK

You can access Valentina Server using native libraries or plugins in many APIs and IDEs available for Linux, macOS, and Windows:

• C
• C++
• Objective-C (macOS)
• Objective-C (iOS)
• COM (Windows)
• Java
• LiveCode (Revolution)
• .NET (Windows)
• PHP
• Python
• Ruby
• Xojo (REALbasic)

Each ADK implements the VConnection⁠ class, which accepts the following connection parameters:

VConnection( 	
    inHost as String, 
    inUserName as String, 
    inUserPassword as String, 
    inPort as Integer = 15432,
    inTimeOut as Integer = 5,
    inOptions as String = "" ) 

Where:

• inHost – The IP address or DNS name of the host.
• inUserName – The user name (sa by default).
• inUserPassword – The user password (sa by default).
• inPort – The port forwarded to the Valentina Server container.
• inTimeOut – Timeout in seconds to wait for a server response.
• inOptions – A string of additional options (embedded signature).

This connection works for Valentina, SQLite and DuckDB databases.

For more information about ADKs, see here⁠.

⁠Technical Support

You can ask questions about Valentina Server on the Paradigma Software forums⁠.

We use the popular MANTIS open-source bug tracker to track feature requests, improvements, and issues.
Before submitting a request, please check the tracker⁠ if:

• Something does not work as you expect.
• Something works but could be improved.
• You have a feature idea that would make the product more useful or productive.

While the team cannot guarantee that every request will be implemented, we consider every submission that comes through our MANTIS server.

⁠Documentation

Learn more about Valentina Server here⁠.