📗 Backend Docs (#131)

Adds dev instructions from ov-deploy

docs/dev.md

@@ -0,0 +1,94 @@
+# Development
+
+## `ov`
+
+The `ov` script is the primary Open Vault command line script. This contains a number of pre-built commands to do basic operations.
+
+### Usage
+
+`ov COMMAND [args]`
+
+```bash title="ov --help"
+COMMANDS:
+
+  b | build           build the docker images
+  c | cmd             run a compose command
+  cover | coverage    Run the test suite with coverage
+  d | dev             start a development server
+  m | manage          run a wagtail manage.py command
+  s | shell           run a django shell command with the app context
+  t | test            Run the test suite
+  tui                 Run an interactive TUI
+```
+
+### Commands
+
+#### `b` | `build`
+
+: Build the docker images locally.
+
+!!! abstract "Pass options to docker build"
+
+    Additional docker arguments can be passed to this command.
+
+    For example, to force a rebuild of the images:
+
+    ```bash
+    ov b --no-cache
+    ```
+
+#### `c` | `cmd`
+
+: Run a `docker compose` command with the base config files in place.
+
+#### `d` | `dev`
+
+: Run Development Environment
+
+: Run the development environment, with `docker compose`, and follow container logs.
+
+!!! abstract "Pass options to docker compose"
+
+    Additional compose arguments can be passed. For example, to rebuild the containers before running:
+
+    ```bash
+    ov d --build
+    ```
+
+#### `m` | `manage`
+
+: Run a `manage.py` command in the docker context.
+
+#### `s` | `shell`
+
+: Enter into a python django shell interpreter, with the application context loaded.
+
+## Examples
+
+The following are some useful examples of development commands that might be run:
+
+### Migrate database
+
+Generating the migration files can be accomplished with:
+
+```bash
+ov m makemigrations
+```
+
+To Run the database migrations:
+
+```bash
+ov m migrate
+```
+
+### Show the logs
+
+Show the docker compose logs
+```bash
+ov c logs
+```
+
+Show logs for just the frontend
+```bash
+ov c logs ov-frontend
+```

docs/reference/index.md

@@ -1 +1,4 @@
 # Reference
+
+## API
+TODO: Add API docs

docs/setup.md

@@ -0,0 +1,105 @@
+# Setup
+
+## Prerequisites
+This page describes how to run the development environment. You can run the development environment locally, or in a docker container.
+
+### Local
+This is the recommended way to run the development environment, for ease of use and speed.
+- `python`
+- `pip`
+- Running Postgres image
+
+Use pip to install [PDM](https://pdm.fming.dev/), the package manager used for this project.
+
+```bash
+pip install pdm
+```
+
+Install the dependencies with PDM
+
+```bash
+pdm install
+```
+
+You can now run the `ov` command to interact with the development environment.
+
+???+ question "Help! How do I ... ?"
+    For a full list of available commands, run 
+    ```bash
+    ov -h
+    ```
+
+    For additional information, see the [dev#ov](dev.md#ov) section of the development documentation.
+
+
+???+ cmd "Activate virtual environment"
+    If you are not already in a virtual environment, activate the one created by PDM.
+
+    ```bash
+    $(pdm venv activate)
+    ```
+### Database
+The development environment requires a running Postgres database. The easiest way to run this is with a docker container.
+
+```bash
+docker run --name ov-db -e POSTGRES_PASSWORD="YOUR POSTGRES PASSWORD HERE" -p 5432:5432 -d postgres:alpine
+```
+
+### Docker
+The development environment can also be run in docker containers, which includes a database configuration.
+- `docker compose` installed
+
+
+???+ abstract "Requirements"
+
+    - [docker](https://docs.docker.com/get-docker/)
+    - [docker compose](https://docs.docker.com/compose/install/)
+
+    Running the services outside of docker is possible, but not supported in this context.
+
+## Setup
+### 0. Clone repository
+
+```bash title="Clone repository"
+git clone https://github.com/WGBH-MLA/ov-wag.git
+```
+
+### 1. Create the backend secrets file
+
+In `ov-wag`, create a file called `.env` with the following contents:
+
+```bash title="ov-wag/.env"
+OV_DB_ENGINE=django.db.backends.postgresql
+OV_DB_PORT=5432
+OV_DB_NAME=ov
+OV_DB_USER=postgres
+OV_DB_PASSWORD="YOUR POSTGRES PASSWORD HERE"
+
+OV_BASE_URL=http://localhost:3000
+OV_ADMIN_BASE_URL=http://localhost:8000
+```
+
+### 2. (Optional) Build the backend
+If you have local changes, you can build the backend image locally:
+```bash title="Build the backend"
+ov b
+```
+
+### 3. Start the backend
+
+```bash title="Start the backend"
+ov d
+```
+You can now visit the admin interface at [http://localhost:8000/admin](http://localhost:8000/admin)
+
+### 4. Create a superuser
+```bash title="Create a superuser"
+ov m createsuperuser
+```
+
+Follow the prompts to create an admin user.
+
+### 5. Start the frontend
+
+!!! todo "Add frontend setup instructions"
+    Make this link work! [ov-frontend setup](https://wgbh-mla.github.io/ov-frontend/dev/)

docs/style/cmd.css

@@ -0,0 +1,17 @@
+:root {
+    --md-admonition-icon--cmd: url('data:image/svg+xml;charset=utf-8,<?xml version="1.0" encoding="utf-8"?><svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 122.88 103.53" style="enable-background:new 0 0 122.88 103.53" xml:space="preserve"><style type="text/css">.st0{fill-rule:evenodd;clip-rule:evenodd;}</style><g><path class="st0" d="M5.47,0h111.93c3.01,0,5.47,2.46,5.47,5.47v92.58c0,3.01-2.46,5.47-5.47,5.47H5.47 c-3.01,0-5.47-2.46-5.47-5.47V5.47C0,2.46,2.46,0,5.47,0L5.47,0z M31.84,38.55l17.79,18.42l2.14,2.13l-2.12,2.16L31.68,80.31 l-5.07-5l15.85-16.15L26.81,43.6L31.84,38.55L31.84,38.55z M94.1,79.41H54.69v-6.84H94.1V79.41L94.1,79.41z M38.19,9.83 c3.19,0,5.78,2.59,5.78,5.78s-2.59,5.78-5.78,5.78c-3.19,0-5.78-2.59-5.78-5.78S35,9.83,38.19,9.83L38.19,9.83z M18.95,9.83 c3.19,0,5.78,2.59,5.78,5.78s-2.59,5.78-5.78,5.78c-3.19,0-5.78-2.59-5.78-5.78S15.75,9.83,18.95,9.83L18.95,9.83z M7.49,5.41 h107.91c1.15,0,2.09,0.94,2.09,2.09v18.32H5.4V7.5C5.4,6.35,6.34,5.41,7.49,5.41L7.49,5.41z"/></g></svg>');
+  }
+  .md-typeset .admonition.cmd,
+  .md-typeset details.cmd {
+    border-color: rgb(0, 191, 165);
+  }
+  .md-typeset .cmd > .admonition-title,
+  .md-typeset .cmd > summary {
+    background-color: rgba(0, 191, 165, 0.1);
+  }
+  .md-typeset .cmd > .admonition-title::before,
+  .md-typeset .cmd > summary::before {
+    background-color: rgb(0, 191, 165);
+    -webkit-mask-image: var(--md-admonition-icon--cmd);
+    mask-image: var(--md-admonition-icon--cmd);
+  }

mkdocs.yml

@@ -4,6 +4,11 @@ repo_url: https://github.com/WGBH-MLA/ov-wag
 site_url: https://wgbh-mla.github.io/ov-wag/
 edit_uri: ''
 
+nav:
+  - Home: index.md
+  - Setup: setup.md
+  - Develop: dev.md
+  - Reference: reference
 markdown_extensions:
   - admonition
   - attr_list
@@ -93,3 +98,4 @@ extra_css:
   - style/gbh.css
   - style/auth.css
   - style/todo.css
+  - style/cmd.css