README.md

   1 # Content Database
   2 [![Build status](https://gitlab.com/minetest/contentdb/badges/master/pipeline.svg)](https://gitlab.com/minetest/contentdb/pipelines)
   3
   4 Content database for Minetest mods, games, and more.\
   5 Developed by rubenwardy, license GPLv3.0+.
   6
   7 ## Getting started (debug/dev)
   8
   9 Docker is the recommended way to develop and deploy ContentDB.
  10
  11 1. Install `docker` and `docker-compose`.
  12
  13                 sudo apt install docker-ce docker-compose
  14
  15 2. Copy `config.example.cfg` to `config.cfg`.
  16
  17 3. (Optional) Set up mail in config.cfg.
  18    Make sure to set `USER_ENABLE_EMAIL` to True.
  19
  20 4. (Optional) Set up GitHub integration
  21         1. Make a Github OAuth Client at <https://github.com/settings/developers>:
  22         2. Homepage URL - `http://localhost:5123/`
  23         3. Authorization callback URL - `http://localhost:5123/user/github/callback/`
  24         4. Put client id and client secret in `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` in config.cfg.
  25
  26 5. Create config.env:
  27
  28                 POSTGRES_USER=contentdb
  29                 POSTGRES_PASSWORD=password
  30                 POSTGRES_DB=contentdb
  31                 FLASK_DEBUG=1
  32
  33 6. Start docker images:
  34
  35                 docker-compose up --build
  36
  37 7. Setup database:
  38
  39                 ./utils/run_migrations.sh
  40
  41 8. Create initial data
  42         1. `./utils/bash.sh`
  43         2. Either `python setup.py -t` or `python setup.py -o`:
  44                 1. `-o` creates just the admin, and static data like tags, and licenses.
  45                 2. `-t` will do `-o` and also create test packages. (Recommended)
  46
  47 9. View at <http://localhost:5123>.
  48    The admin username is `rubenwardy` and the password is `tuckfrump`.
  49
  50 In the future, starting CDB is as simple as:
  51
  52         docker-compose up --build
  53
  54 To hot/live update CDB whilst it is running, use:
  55
  56         ./utils/reload.sh
  57
  58 This will only work with python code and templates, it won't update tasks or config.
  59
  60
  61 ## How-tos
  62
  63 ```sh
  64 # Hot/live reload (only works with FLASK_DEBUG=1)
  65 ./utils/reload.sh
  66
  67 # Cold update a running version of CDB with minimal downtime (production)
  68 ./utils/update.sh
  69
  70 # Enter docker
  71 ./utils/bash.sh
  72
  73 # Run migrations
  74 ./utils/run_migrations.sh
  75
  76 # Create new migration
  77 ./utils/create_migration.sh
  78 ```
  79
  80
  81 ### VSCode: Setting up Linting
  82
  83 * (optional) Install the [Docker extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)
  84 * Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
  85         * Click no to installing pylint (we don't want it to be installed outside of a virtual env)
  86 * Set up a virtual env
  87         * Replace `psycopg2` with `psycopg2_binary` in requirements.txt (because postgresql won't be installed on the system)
  88         * `python3 -m venv env`
  89         * Click yes to prompt to select virtual env for workspace
  90         * Click yes to any prompts about installing pylint
  91         * `source env/bin/activate`
  92         * `pip install -r requirements`
  93         * `pip install pylint` (if a prompt didn't appear)
  94         * Undo changes to requirements.txt
  95
  96 ### VSCode: Material Icon Folder Designations
  97
  98 ```json
  99 "material-icon-theme.folders.associations": {
 100         "packages": "",
 101         "tasks": "",
 102         "api": "",
 103         "meta": "",
 104         "blueprints": "routes",
 105         "scss": "sass",
 106         "flatpages": "markdown",
 107         "data": "temp",
 108         "migrations": "archive",
 109         "textures": "images",
 110         "sounds": "audio"
 111 }
 112 ```
 113
 114
 115 ## Database
 116
 117
 118 ```mermaid
 119 classDiagram
 120
 121 User "1" --> "*" Package
 122 User --> UserEmailVerification
 123 User "1" --> "*" Notification
 124 Package "1" --> "*" Release
 125 Package "1" --> "*" Dependency
 126 Package "1" --> "*" Tag
 127 Package "1" --> "*" MetaPackage : provides
 128 Release --> MinetestVersion
 129 Package --> License
 130 Dependency --> Package
 131 Dependency --> MetaPackage
 132 MetaPackage "1" --> "*" Package
 133 Package "1" --> "*" Screenshot
 134 Package "1" --> "*" Thread
 135 Thread "1" --> "*" Reply
 136 Thread "1" --> "*" User : watchers
 137 User "1" --> "*" Thread
 138 User "1" --> "*" Reply
 139 User "1" --> "*" ForumTopic
 140
 141 User --> "0..1" EmailPreferences
 142 User "1" --> "*" APIToken
 143 APIToken --> Package
 144 ```