Metadata-Version: 2.4
Name: amarcord
Version: 1.5
Summary: A ModulAR CollectOR of metaData - serial edition
Author-email: Philipp Middendorf <philipp.middendorf@desy.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: aiohttp==3.14.1
Requires-Dist: aiosqlite==0.22.1
Requires-Dist: alembic==1.17.2
Requires-Dist: anyio==4.14.1
Requires-Dist: asyncmy==0.2.11
Requires-Dist: asyncpg==0.31.0
Requires-Dist: cryptography==49.0.0
Requires-Dist: fastapi==0.139.0
Requires-Dist: gunicorn==26.0.0
Requires-Dist: lark==1.3.1
Requires-Dist: mstache==0.3.0
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pint==0.25.3
Requires-Dist: pydantic==2.13.4
Requires-Dist: pymysql==1.2.0
Requires-Dist: python-magic==0.4.27
Requires-Dist: python-multipart==0.0.32
Requires-Dist: sqlalchemy==2.0.51
Requires-Dist: starlette==1.3.1
Requires-Dist: structlog-overtime==1.0.1
Requires-Dist: structlog==26.1.0
Requires-Dist: typed-argparse==0.3.1
Requires-Dist: typed-argument-parser==1.12.0
Requires-Dist: uvicorn==0.50.2
Description-Content-Type: text/markdown

<div align="center">
  <p>
	<a href="https://amarcord.pages.desy.de/amarcord/"><img src="/docs/source/amarcord-logo-with-title.png" alt="AMARCORD Logo with Title Text"></a>
  </p>
  <p>
	  <em>A Flexible Database for Multi-Dimensional Serial Crystallography</em>
  </p>

  <img src="https://gitlab.desy.de/amarcord/amarcord/badges/main/pipeline.svg" alt="Pipeline Status Badge" />
  <img src="https://gitlab.desy.de/amarcord/amarcord/badges/main/coverage.svg?min_good=79" alt="Test Coverage Badge" />
  <img src="https://gitlab.desy.de/amarcord/amarcord/-/badges/release.svg" alt="Latest Release Badge" />
</div>

---

**Documentation**: We have extensive documentation in the form of *GitLab pages* on https://amarcord.pages.desy.de/amarcord/

**Source Code**: https://gitlab.desy.de/amarcord/amarcord

---

AMARCORD is a free and open-source database application designed to gather metadata about chemicals, runs and analysis results of serial crystallography (SX) experiments. The software features an easy-to-use, web-based user interface and was used in numerous experiments in order to cope with both the amount of data collected, as well as different experimental groups working during the same beam time. It was further extended not only to collect metadata, but also trigger analysis jobs and ingest the resulting figures of merit, resulting in a complete framework for running an SX experiment.

# Python setup

## uv
AMARCORD uses [uv](https://docs.astral.sh/uv/) for managing its dependencies. So either install that and run:

```
uv venv
```

to create a venv with all dependencies installed. Running programs is then simply

```
uv run amarcord-<program-name> <arguments>
```

## Plain pip

Since we have `requirements.txt` files, as long as you don’t want to add new dependencies, you can just create a virtual environment and activte it to get up and running:

```
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## Notes for Microsoft Windows users

We’re using [python-magic](https://pypi.org/project/python-magic/) to determine the type of uploaded files. This depends on `libmagic` which is not available on Windows. You can either do everything using [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) or you can manually `pip install python-magic-bin` which solves the issue.

If you manually created your virtual environment, the way to activate it on Windows isn’t

``` shell
source venv/bin/activate
```

but rather

``` shell
source venv/Scripts/activate
```

this is for [idiotic reasons](https://stackoverflow.com/questions/43826134/why-is-the-bin-directory-named-differently-scripts-on-windows).

## How to start a backend server

To start a backend server, you have to create a database first. This isn't done implicitly when starting the web server, since this created problems. It's easy to create one, however, just do this (yes, there are four `/` in the URL):

```
python amarcord/cli/upgrade_db_to_latest.py --db-connection-url 'sqlite+aiosqlite:////tmp/test.db'
```

To start a web server with a “blank”, but usable SQLite database in `/tmp/test.db` (adapt if you're on Windows), run:

```
DB_URL='sqlite+aiosqlite:////tmp/test.db' uvicorn --port 5000 amarcord.cli.webserver:app
```

which will open a web server on port `5000`.

You won't see much when you point your browser to http://localhost:5000 though, because we haven't built the front-end yet, and we don't have a prebuilt version of the front-end in the repository. But, read on.

## How to build and start the frontend

The frontend is written in [Elm](https://elm-lang.org/). You can download the `elm` compiler binary at the [Install Elm](https://guide.elm-lang.org/install/elm.html) web site.

If you just want to build the necessary files for the frontend, without being an active developer, you can simply navigate to the `frontend/` directory and execute the `./build-elm-manually.sh` script. It will put all the assets into `frontend/output/build`, which is the default search path for the web server, which you can run,  described above. Then go to http://localhost:5000/index.html in your browser.

To run a *live development environment*, you need [elm-live](https://github.com/wking-io/elm-live) which, unfortunately, needs [node.js](https://nodejs.org/en/). But you can install that really easily on different platforms.

Assuming you’ve got it installed, run:

```
npm install
```

To install the dependencies (you can also use [Yarn](https://yarnpkg.com/), which might be more performant). Then, start a development server via:

```
./run-live-dev-env.sh
```

And point your browser to http://localhost:8000.


## Nix

To speed up CI builds and unify dependencies, AMARCORD uses the [Nix package manager](https://nixos.org/). It also uses flakes, so enable those in your `~/.config/nix/nix.conf`:

```
experimental-features = nix-command flakes
```

If you have Nix installed, building the AMARCORD Python package is as simple as

```shell
nix build '.#amarcord-python-package'
```

To build a Docker container:

```shell
nix build '.#amarcord-docker-image
```

To get a development shell with the Python dependencies:

```shell
nix develop
```

To get a development shell with the Elm dependencies:

```shell
cd frontend
nix develop '..#frontend'
```

For the CI build, we have an instance of gitlab-runner on `cfeld-vm04` using the shell executor right now.
