How-To start a local model-server

If you are interested in a more practical usage of what is presented here, check out the samples project
To run a light version of the model-sever, check out How-To Run the Light model-server in MPS as a Plugin

Backends: In Memory vs. Database

The model-server will by default require a database backend. The -jdbcconf flag allows you to provide a custom JDBC configuration file. While this setup is ideal for deployment, it might not what you need in the beginning. During development or to perform tests, it is recommended to start the model-server with in-memory storage. This can be achieved by adding the -inmemory flag to the executable.

Running a model-server

The following list gives an overview of the many ways to run a model-server:

1. Docker

We publish a Docker container of the model-server over on Docker Hub. To run the model-server container with the in-memory backend, simply call the following.

$ docker run --rm -p 28101:28101 modelix/modelix-model:latest -inmemory

2. docker-compose

If you use docker-compose, use the following.

Content of docker-compose.yml
name: model-server-run-in-memory

services:
  model-server:
    image: modelix/model-server:latest0
    ports:
      - 28101:28101
    command: [ "-inmemory" ]

Run using docker-compose via:

$ docker-compose up
For more integrated examples, have a look at the metrics and monitoring capabilities, which shows how to start the model-server using docker-compose.

For more complex setups, which require a database backend, you can use the following:

Content of docker-compose.yml
name: model-server-run-database

services:
    model-server:
        image: modelix/model-server:4.5.0
        restart: always
        healthcheck:
          test: ["CMD-SHELL", "curl http://localhost:28101/health"]
          interval: 2s
          timeout: 3s
          retries: 10
        depends_on:
          model-server-db:
            condition: service_healthy
        environment:
          jdbc_url: jdbc:postgresql://model-server-db:5432/modelix?currentSchema=modelix
        ports:
        - 28101:28101

    model-server-db:
      image: postgres:16
      environment:
        POSTGRES_PASSWORD: modelix
        POSTGRES_DB: modelix
        POSTGRES_USER: modelix
        PGDATA: /var/lib/postgresql/data/pgdata
      healthcheck:
        test: ["CMD-SHELL", "pg_isready -U modelix -d modelix"]
        interval: 10s
        timeout: 3s
        retries: 10
      volumes:
        - model-server-db:/var/lib/postgresql/data
        - ./init-database.sql:/docker-entrypoint-initdb.d/init-database.sql:z

volumes:
  model-server-db: {}
Content of init-database.sql
CREATE SCHEMA modelix;
GRANT ALL ON SCHEMA modelix TO modelix;

CREATE TABLE modelix.model
(
    key character varying NOT NULL,
    value character varying,
    reachable boolean,
    CONSTRAINT kv_pkey PRIMARY KEY (key)
);
GRANT ALL ON TABLE modelix.model TO modelix;

Run using docker-compose via:

$ docker-compose up

3. Gradle via Dependency

When using Gradle, you can run a model-server by adding a dependency to org.modelix:model-server, as shown in the following minimal working example.

Content of minimal build.gradle.kts to run a model-server in memory
plugins {
    application
}

repositories {
    mavenCentral()
    maven { url = uri("https://artifacts.itemis.cloud/repository/maven-mps/") }
}

dependencies {
    implementation("org.modelix:model-server:4.6.0")
}

application {
    mainClass.set("org.modelix.model.server.Main")
}

tasks.run.configure {
    args("-inmemory")
    // note: you can add other arguments here, e.g.
    // args("-inmemory", "-dumpin", "/path/to/dump/file.dump")
}

You can start the model-server simply by running

./gradlew run

4. Gradle via Source

Use git to check out the modelix core repository from

https://github.com/modelix/modelix.core

To run the model-server with default configuration run:

[modelix.core] $ ./gradlew model-server:run
You will have to build the project first, which might take some time depending on your hardware.

To give arguments to the gradle run command, you have to add them via the --args flag:

./gradlew model-server:run --args='-jdbcconf path-to-my-database.properties -dumpout'

5. In Process (Kotlin)

This rather advanced version allows you to run the model-server inside your own application. We primarily use this approach for testing, but theoretically it could be applied elsewhere. You can find an examples of this in the following code fragment: