feat: add anyvlm database (#28)

close #23

* Started some docs work for #25

Author: korikuzma

.env.example

@@ -0,0 +1,13 @@
+###############
+# BASIC SETUP #
+###############
+
+# Storage configuration -- see "Configuration" -> "Object Storage" in the docs
+ANYVLM_STORAGE_URI=postgresql://anyvlm:anyvlm-pw@localhost:5435/anyvlm
+
+############
+# OPTIONAL #
+############
+
+## Testing - see "Contributing" -> "Testing" in the docs
+ANYVLM_TEST_STORAGE_URI=postgresql://anyvlm_test:anyvlm-test-pw@localhost:5436/anyvlm_test

.github/workflows/python-package.yaml

@@ -47,6 +47,7 @@ jobs:
         run: uv run pytest
         env:
           ANYVLM_ANYVAR_TEST_STORAGE_URI: postgresql://postgres:postgres@localhost:5432/postgres
+          ANYVLM_TEST_STORAGE_URI: postgresql://postgres:postgres@localhost:5432/postgres
   lint:
     name: lint
     runs-on: ubuntu-latest

compose.test.yaml

@@ -0,0 +1,11 @@
+services:
+  anyvlm_test_db:
+    image: postgres:17
+    tmpfs:
+      - /var/lib/postgresql/data
+    ports:
+      - 127.0.0.1:5436:5432
+    environment:
+      - POSTGRES_DB=anyvlm_test
+      - POSTGRES_USER=anyvlm_test
+      - POSTGRES_PASSWORD=anyvlm-test-pw

compose.yaml

@@ -0,0 +1,15 @@
+services:
+  anyvlm_db:
+    image: postgres:17
+    volumes:
+      - anyvlm_vol:/var/lib/postgresql/data
+    ports:
+      - 127.0.0.1:5435:5432
+    environment:
+      - POSTGRES_DB=anyvlm
+      - POSTGRES_USER=anyvlm
+      - POSTGRES_PASSWORD=anyvlm-pw
+
+volumes:
+  anyvlm_vol:
+    external: true

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -0,0 +1,62 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "anyvlm"
+author = "GenomicMedLab"
+html_title = "AnyVLM"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.linkcode",
+    "sphinx_copybutton",
+    "sphinx.ext.autosummary",
+    "sphinx_github_changelog",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "collapse_navigation": False,
+}
+
+# -- autodoc things ----------------------------------------------------------
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../"))
+autodoc_preserve_defaults = True
+
+# -- get version -------------------------------------------------------------
+from anyvlm import __version__  # noqa: E402
+
+version = release = __version__
+
+
+# -- linkcode ----------------------------------------------------------------
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+    filename = info["module"].replace(".", "/")
+    return f"https://github.com/genomicmedlab/anyvlm/blob/main/src/{filename}.py"
+
+
+# -- code block style --------------------------------------------------------
+pygments_style = "default"
+pygements_dark_style = "monokai"

docs/source/configuration/docker_compose.rst

@@ -0,0 +1,31 @@
+Configuring Docker Compose
+!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+This page describes how to use the provided ``compose.yaml`` file to start AnyVLM alongside its dependencies, and highlights some configuration options you can customize for your environment.
+
+Overview
+--------
+
+The compose file defines one main service:
+
+* ``anyvlm_db`` - PostgreSQL database for AnyVLM
+
+It also defines a Docker volume:
+
+* ``anyvlm_vol`` - storage for the AnyVLM PostgreSQL data directory
+
+This volume is declared as ``external: true``, so it must exist before
+you run ``docker compose up``. For example:
+
+.. code-block:: bash
+
+   docker volume create anyvlm_vol
+
+Running the stack
+-----------------
+
+After creating the external volumes and configuring any optional environment variables, you can start the stack with:
+
+.. code-block:: bash
+
+   docker compose up

docs/source/configuration/dotenv_example.rst

@@ -0,0 +1,4 @@
+Example .env File
+!!!!!!!!!!!!!!!!!
+
+.. literalinclude:: ../../../.env.example

docs/source/configuration/index.rst

@@ -0,0 +1,16 @@
+Configuration
+!!!!!!!!!!!!!
+
+This section details AnyVLM configuration. It is broken down into the following subsections:
+
+* :doc:`Object Storage <storage>`: define database connection
+* :doc:`Example .env file <dotenv_example>`: use a ``.env`` file to declare environment variables when running REST API service
+* :doc:`Docker Compose <docker_compose>`: edit the provided Docker Compose file to tailor it to your needs
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   Storage<storage>
+   Example .env file<dotenv_example>
+   Docker Compose<docker_compose>

docs/source/configuration/storage.rst

@@ -0,0 +1,16 @@
+Object Storage Configuration
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Storage Connection
+==================
+
+Use the ``ANYVLM_STORAGE_URI`` environment variable to pass a `libpq connection string <https://www.postgresql.org/docs/current/libpq.html>`_ to the PostgreSQL connection constructor.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Environment Variable
+     - Default Value
+   * - ``ANYVLM_STORAGE_URI``
+     - ``"postgresql://postgres@localhost:5432/anyvlm"``