The application relies on its functionality on a running server written in Python. The implementation of the server is to be found on src/server (in the future, we will have a dedicated page for its API).

In the ideal scenario, users won't even know that the server is running. They will see only a server status icon in a footer and they will be able to change a few parameters in settings.

When developing, it is recommended to use uv package manager. The following steps then explain how to build the server:

1. Go to the root of the project.
2. Run uv init to initialise the virtual environment, or run uv init --python python3.12 to specify the Python version (3.12 is currently the version we build the server for).
3. Run uv pip install pyinstaller to add PyInstaller into the virtual environment.
4. Run uv add -r src/server/requirements.txt to install all other necessary libraries for the server executable.
5. Run source .venv/bin/activate to activate the environment.
6. Run npm run build:server:uv to build the server into dist-server folder.

If you want to delete the virtual environment and other files created by uv, use rm -rf .venv/ uv.lock pyproject.toml.

It is of course possible to build the server also without using any virtual environment, that is actually what the server building workflow does. This time, the script is not build:server:uv, but just build:server!

In any case, the server is built using PyInstaller and this is the whole command under the hood: pyinstaller --onefile src/server/main.py --name MolStarAppServer --distpath ./dist-server --workpath ./tmp/server --specpath ./tmp/server --clean. The built executable will be thhus located in dist-server folder, as said before.

The application spawns the server automatically when it is launched, but if you need to, you can start the server yourself using npm run server. This script starts the server with default parameters. Talking about parameters, let's talk about them in more detail:

• Type: String
• Default: localhost
• Description: Specifies the host address to bind the server to
• Example: --host 0.0.0.0 (bind to all interfaces)

• Type: Integer
• Default: 41050
• Description: Specifies the port number to bind the server to
• Example: --port 8080

• Type: String
• Default: dev
• Description: Sets the server environment mode
• Valid values: dev, prod (or development, production)
• Example: --env prod

• Type: List of strings
• Default: [] (empty list)
• Description: Specifies allowed origins for Cross-Origin Resource Sharing (CORS). Multiple origins can be provided separated by spaces. These two are always present: file:// and http://localhost:<PORT>.
• Example: --cors http://localhost:3000 http://127.0.0.1:3000

• Type: Boolean flag
• Default: False
• Description: Enables automatic server reload when code changes are detected. Only effective in development mode (--env dev).
• Example: --reload (no value needed, presence of flag enables it)

./dist-server/MolStarAppServer --port 8080 --cors http://localhost:3000 --reload

./dist-server/MolStarAppServer --host 0.0.0.0 --port 80 --env prod

./dist-server/MolStarAppServer --env dev --cors http://localhost:3000 http://127.0.0.1:3000 http://localhost:5173 --reload