AmCAT4

Server for document management and automatic text analysis, developed as part of OPTED. Learn more

See also the API Documentation

ElasticSearch and SeaweedFS

AmCAT requires as least an elasticsearch instance, and optionally a SeaweedFS instance for file storage. The easiest way to set these up for development is to use docker-compose:

docker compose -f dev/docker-compose.yml up -d

This creates an elasticsearch instance at localhost:9200 and a SeaweedFS instance at localhost:9333. Note that this docker-compose file is completely unsecured, so this should be configured differently in production.

Alternatively, only run Elasticsearch

If you just want to run elasticsearch without using docker-compose, you can run:

sudo docker run --name elastic8 -dp 9200:9200 -e "xpack.security.enabled=false" -e ES_JAVA_OPTS="-Xms1g -Xmx1g" -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.6.1

Installing from source

To install AmCAT4 from github, run:

git clone https://github.com/ccs-amsterdam/amcat4
cd amcat4

You can now directly run AmCAT4 with uv, which will install a virtual environment and all needed packages:

uv run amcat4 run

This will run the API at (default) locahost port 5000. To see documentation, visit http://localhost:5000/docs (Swagger, which comes with interactive "try now" mode) or http://localhost:5000/redoc (redoc, looks somewhat nicer)

Of course, this new instance is still completely empty, so there is little to see. If you want to add some test data, you can use the create-test-data command, which will upload some State of the Union speeches:

uv run amcat4 create-test-index

(Note: if you get an SSL error, especially on a mac, try running env/bin/pip install -U certifi

Security and configuration

By default, the API is unsecured (no client authentication is necessary) and it expects an elasticsearch instance at localhost:9200.

AmCAT reads its configuration from environment variables, so you can either pass them directly or by creating a .env file. You can modify the example .env file or interactively create the .env file using:

uv run amcat4 config

Using AmCAT

Congrats, you've just installed the AmCAT backend!

To use this, you probably want to look at either the react-based web client or the python API bindings or R API bindings

(there will also be an open client soon, stay tuned)

Unit tests

To run the unit tests:

uv run pytest

Please make sure to run these tests before making any commits!