Marvin Installation Guide¶

Overview¶

Marvin consists of both backend and frontend components, each of which must be installed and configured to enable full
functionality.

The backend (Marvin Web Services) is a SpringBoot application that
provides RESTful API endpoints for operations such as transforming, converting, exporting, and analyzing chemical
structures.
The frontend is a React application, which can be seamlessly embedded into HTML or integrated with other frontend
frameworks like Vue or Angular.

Our distribution packages bundle both components, tailored for specific platforms (Windows, Mac, Linux, and Docker image
as well), making them easy to install or deploy.
In these packages, the backend runs an instance of Marvin Web Services SpringBoot app, while the frontend is served as
static content.

The two components rely on each other and are tied together through a secure communication:

The Marvin frontend is granted a valid license by the backend, without which it remains disabled and shows an error
message.
The Marvin Web Services backend only accepts requests coming from and signed by a Marvin frontend, and cannot
therefore be used outside the context of Marvin editor.

Quickstart¶

The following steps will guide you through the easiest installation process, in which most settings and configurations
are left untouched.

You can skip steps 1-2. if you already have Java installed, and steps 4-5 if you already have your license key and
license-manager configuration ready.

Step	Windows	macOS	Linux
1. Make sure at least Java 21 is installed Test it with `java -version` in a terminal:	`Win + R`, type `cmd` and hit Enter	`Applications > Utilities > Terminal`	`Ctrl + Alt + T`
2. Get Temurin OpenJDK if necessary here
3. Get and run installer from our download page	64 bit .exe	.dmg	.deb (Debian/Ubuntu) .rpm (Fedora)
4. Get your own license key from your account
5. Create a license settings with the following content (replace license key)	`C:/Users/<username>/Chemaxon/license-manager.properties`	`/root/.chemaxon/license-manager.properties`	`/root/.chemaxon/license-manager.properties`
server=https://license.chemaxon.com license-key=
6. Start the Marvin WS service	execute `C:\Program Files\Chemaxon\marvinws\run-marvinws` (available in Start Menu)	execute `/Applications/Marvin\ Webservices/run-marvinws`	`sudo systemctl start marvinws` *
7. Open Marvin in your browser: http://localhost:8080

* marvinws is supposed to be automatically enabled and running on Linux after installation. Test it with
sudo systemctl status marvinws

Deploy Marvin with Docker Compose¶

docker-compose.yml starts a standalone Marvin deployment for internal services
and external, on-premises installations. It includes the services needed by Marvin
and Centralized Charts:

Service	Default URL	Purpose
`marvin`	`http://localhost:8080`	Marvin frontend and backend
`jms-calculations`	`http://localhost:8064`	JChem Microservices calculations used by Centralized Charts
`marvin-rendering-backend`	`http://localhost:3000`	Large-scale structure rendering and conversion

Prerequisites¶

Docker Engine with Docker Compose v2 (docker compose)
Network access to artifacts.chemaxon.com
Artifactory credentials authorized to pull every image in the compose file
A valid license server key (LICENSE_KEY_MARVIN; other services reuse it unless overridden)
Three available host ports (8080, 8064, and 3000 by default)

Obtain the deployment files¶

Download the versioned archive from Artifactory. Each Marvin build publishes a
single tarball, marvin-docker-compose-<BUILD_VERSION>.tar.gz, that contains
docker-compose.yml and a generated .env with image tags for that build.

Release bundles use:

chemaxon_toolkit_marvin-generic-release-local/com/chemaxon/marvin/marvin/<BUILD_VERSION>/marvin-docker-compose-<BUILD_VERSION>.tar.gz

Extract the archive into a working directory. On macOS, Linux, and Windows
(Command Prompt or PowerShell), run:

tar -xzf marvin-docker-compose-<BUILD_VERSION>.tar.gz

Windows (File Explorer): right-click marvin-docker-compose-<BUILD_VERSION>.tar.gz
and choose Extract All.... On older Windows builds that do not extract .tar.gz
natively, use 7-Zip (open the archive, then extract
docker-compose.yml and .env into the same folder).

Use docker-compose.yml and .env from the same archive. Mixing files from
different builds can produce an unsupported service set.

Configure `.env`¶

Open the extracted .env and set LICENSE_KEY_MARVIN.

Docker Compose automatically reads .env when it is in the working directory
beside docker-compose.yml.

Operating systems hide files whose names start with a dot (.env, .env.example)
in graphical file browsers. Enable hidden files if the environment file does not
appear next to docker-compose.yml.

macOS (Finder): press Command-Shift-Period (⌘⇧.). Press the same shortcut
again to hide them.

Windows (File Explorer):

Windows 11: View → Show → Hidden items
Windows 10: View → Hidden items

The files remain visible in a terminal (ls -a on macOS/Linux, dir /a on
Windows) even when Finder or Explorer hides them.

Set LICENSE_KEY_MARVIN. Leave LICENSE_KEY_JMS_CALCULATIONS and
LICENSE_KEY_MARVIN_RENDERING_BACKEND empty to reuse that key; set them
only to override. An empty LICENSE_KEY_MARVIN is not reused for the other
services.

Variable	Service	Required
`LICENSE_KEY_MARVIN`	Marvin frontend and backend	Yes
`LICENSE_KEY_JMS_CALCULATIONS`	JMS calculations	No; empty values use `LICENSE_KEY_MARVIN`
`LICENSE_KEY_MARVIN_RENDERING_BACKEND`	Marvin rendering backend	No; empty values use `LICENSE_KEY_MARVIN`

License keys are secrets. Do not commit .env, include it in deployment artifacts,
or paste it into logs or support tickets.

The remaining variables select image versions and published host ports:

Variable	Default source
`MARVIN_VERSION`	The Marvin build version used to publish the bundle
`JMS_CALCULATIONS_VERSION`	The JMS calculations version for that Marvin build
`MARVIN_RENDERING_BACKEND_VERSION`	The rendering backend version for that Marvin build
`MARVIN_PORT`	`8080`
`JMS_CALCULATIONS_PORT`	`8064`
`MARVIN_RENDERING_BACKEND_PORT`	`3000`

Authenticate to Artifactory¶

Authenticate before pulling images:

docker login artifacts.chemaxon.com

Use an access token or API key through your organization's approved secret-handling
method. Do not put registry credentials in .env; the compose file does not read
them.

Confirm that all configured images are accessible:

docker compose --env-file .env config --images
docker compose --env-file .env pull

If one image cannot be pulled, verify both its version and the account's entitlement
to the snapshot or release repository shown in docker-compose.yml.

Start the application¶

From the directory containing docker-compose.yml and .env:

docker compose --env-file .env config
docker compose --env-file .env up -d
docker compose ps

Open http://localhost:8080 by default. The other services listen on their ports
listed above. Service startup may take a short time; inspect status and logs with:

docker compose ps
docker compose logs --tail 100
docker compose logs -f marvin

A basic Marvin backend check is:

curl --fail http://localhost:8080/rest-v1/time

For a remote host, replace localhost with its DNS name and ensure the selected
ports are permitted by the host firewall.

Stop, restart, and upgrade¶

Stop the stack without deleting downloaded images:

docker compose down

Restart one service after configuration or license changes:

docker compose up -d --force-recreate marvin

To upgrade, download a newer marvin-docker-compose-<BUILD_VERSION>.tar.gz,
extract it, re-enter the license keys in .env, and then run:

docker compose pull
docker compose up -d

Keep the previous compose and version values available for rollback. The provided
stack does not define persistent volumes, so docker compose down removes the
containers and their writable container data.