Our goal is to implement an external document management service to hold and provide uploaded documents. Documents can be uploaded and, depending on user access, managed by internal as well as external users.
The goal is NOT to re implement a complex DMS but rather to have a simple and user-friendly way of managing documents with different permissions.
All User Interface interactions should be as simple as possible and easily understandable.
Original RFC that led to alexandria
Requirements
- docker
- docker-compose
After installing and configuring those, download docker-compose.yml and run the following commands:
# only needs to be run once
echo UID=$UID > .env
docker compose up -d
You can now access the api at http://localhost:8000/api/v1/.
To load a set of categories run the following command:
make load_example_data
If alexandria is installed as a package you can use PYTHON_API for interacting with the models in an easier way.
Alexandria is a 12factor app which means that configuration is stored in environment variables. Different environment variable types are explained at django-environ.
Additional authorization and validation of the models is handled by DGAP.
A list of configuration options which you need
-
Django configuration
-
SECRET_KEY
: A secret key used for cryptography. This needs to be a random string of a certain length. See more. -
ALLOWED_HOSTS
: A list of hosts/domains your service will be served from. See more. -
DATABASE_ENGINE
: Database backend to use. See more. (default: django.db.backends.postgresql) -
DATABASE_HOST
: Host to use when connecting to database (default: localhost) -
DATABASE_PORT
: Port to use when connecting to database (default: 5432) -
DATABASE_NAME
: Name of database to use (default: alexandria) -
DATABASE_USER
: Username to use when connecting to the database (default: alexandria) -
DATABASE_PASSWORD
: Password to use when connecting to database
-
-
Authentication configuration
-
OIDC_OP_USER_ENDPOINT
: Userinfo endpoint for OIDC -
OIDC_VERIFY_SSL
: Set tofalse
if you want to disable verifying SSL certs. Useful for development -
OIDC_DRF_AUTH_BACKEND
: Overwrite the default authentication backend with your own -
ALEXANDRIA_OIDC_USER_FACTORY
: Overwrite the default user with your own -
ALEXANDRIA_CREATED_BY_USER_PROPERTY
: Overwrite the default user property which is used for..._by_user
(default: username) -
ALEXANDRIA_CREATED_BY_GROUP_PROPERTY
: Overwrite the default group property which is used for..._by_group
(default: group) -
ALEXANDRIA_GET_USER_AND_GROUP_FUNCTION
: Overwrite the import string if further configuration how user and group are determined is needed.
-
-
Authorization configurations
-
Data validation configuration
-
ALEXANDRIA_VALIDATION_CLASSES
: Comma-separated list of DGAP classes that define custom validations. A default base class is used for file validation. ExtendAlexandriaValidator
for own validations.
-
-
Thumbnail configuration (optional)
-
ALEXANDRIA_ENABLE_THUMBNAIL_GENERATION
: Set tofalse
to disable thumbnail generation- Check the docker-compose file for an example on how to set up generation with s3 hooks
-
ALEXANDRIA_THUMBNAIL_WIDTH
: Width of generated thumbnails -
ALEXANDRIA_THUMBNAIL_HEIGHT
: Height of generated thumbnails -
ALEXANDRIA_ENABLE_CHECKSUM
: Set tofalse
to disable file checksums. Checksums are calculated after upload to allow later verification (not implemented in Alexandria)
-
-
Storage configuration
Storage backends are configured globally. The storable object bears information on the encryption status allowing the ORM appropriate handling of the data.
-
ALEXANDRIA_FILE_STORAGE
: Set the backend for file uploads.django-storages
is available (default:alexandria.storages.backends.s3.S3Storage
)
Encryption:
-
ALEXANDRIA_ENABLE_AT_REST_ENCRYPTION
: Set totrue
to enable at-rest encryption of files (enabling this causes an error unlessALEXANDRIA_ENCRYPTRION_METHOD
is set to a supported method) -
ALEXANDRIA_ENCRYPTION_METHOD
: Define encryption method that is applied to uploaded objects. Available values depend on storage backend's capabilities (default:None
)- available methods
- None: no at-rest encryption
-
ssec-global
: encrypt all files with the same key (requires:ALEXANDRIA_FILE_STORAGE
:alexandria.storages.backends.s3.S3Storage
)
- available methods
Supported backends:
-
FileSystemStorage
: files are stored to theMEDIA_ROOT
directory -
S3Storage
: files are uploaded to the S3 object storage configured accordinglyrequired configuations:
-
ALEXANDRIA_S3_ACCESS_KEY
: identity -
ALEXANDRIA_S3_SECRET_KEY
: password to authorize identity -
ALEXANDRIA_S3_ENDPOINT_URL
: the url of the service -
ALEXANDRIA_S3_BUCKET_NAME
: the bucket name of the storage to access objects in path notation (not subdomain)
The development setup features a minio service, implementing the S3 protocol. To use SSE-C in development make sure to generate a certificate for the minio container and set
ALEXANDRIA_S3_VERIFY
tofalse
. -
-
-
ClamAV
-
ALEXANDRIA_CLAMD_ENABLED
: Set this toTrue
to enable ClamAV (virus scanner). -
ALEXANDRIA_CLAMD_SOCKET
: ClamAV socket -
ALEXANDRIA_CLAMD_USE_TCP
: Use TCP to connect to ClamAV service -
ALEXANDRIA_CLAMD_TCP_SOCKET
: ClamAV service socket -
ALEXANDRIA_CLAMD_TCP_ADDR
: ClamAV service address
-
-
Document Merge Service Enable conversion of docx/odt files to pdf directly in alexandria.
-
ALEXANDRIA_ENABLE_PDF_CONVERSION
: Set this toTrue
to enable the pdf conversion endpoint. -
ALEXANDRIA_DMS_URL
: URL where the document merge service is running
-
-
WebDAV
-
ALEXANDRIA_USE_MANABI
: Set totrue
to enable WebDAV via Manabi -
ALEXANDRIA_MANABI_DAV_URL_PATH
: Set the path segement where WebDAV is being served -
ALEXANDRIA_MANABI_DAV_SCHEME
: Set the scheme for the WebDAV URL -
MANABI_SHARED_KEY
: Can be generated with:
import manabi manabi.keygen()
-
For development, you can also set the following environemnt variables to help you:
-
ALEXANDRIA_DEV_AUTH_BACKEND
: Set this to "true" to enable a fake auth backend that simulates an authenticated user. RequiresDEBUG
to be set toTrue
as well. -
DEBUG
: Set this to true for debugging during development. Never enable this in production, as it will leak information to the public if you do.
Look at our contributing guidelines to start with your first contribution.
Some notes for maintaining this project can be found in the maintainer's handbook.