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 1. Copy `config.example.cfg` to `config.cfg`.
  16
  17 2. Fill out `config.cfg`
  18         1. Set `SQLALCHEMY_DATABASE_URI` = "postgres://contentdb:password@db:5432/contentdb"
  19         2. Optionally, set the MAIL settings.
  20
  21 3. (Optional) Set up GitHub integration
  22         1. Make a Github OAuth Client at <https://github.com/settings/developers>:
  23         2. Homepage URL - `http://localhost:5123/`
  24         3. Authorization callback URL - `http://localhost:5123/user/github/callback/`
  25         4. Put client id and client secret in `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` in config.cfg.
  26
  27 4. Create config.env:
  28
  29                 POSTGRES_USER=contentdb
  30                 POSTGRES_PASSWORD=password
  31                 POSTGRES_DB=contentdb
  32                 FLASK_DEBUG=1
  33
  34 5. Start docker images:
  35
  36                 docker-compose up --build
  37
  38 6. Setup database:
  39
  40                 ./utils/run_migrations.sh
  41
  42 8. (Optional) create initial data
  43         1. `./utils/bash.sh`
  44         2. Either `python setup.py -o` or `python setup.py -t`
  45         1. `-o` creates just the admin, and static data like tags, and licenses.
  46         2. `-t` will create test pacakges.
  47
  48 9.  View at <http://localhost:5123>.
  49     The admin username is `rubenwardy` and the password is `tuckfrump`.
  50
  51 In the future, starting CDB is as simple as:
  52
  53         docker-compose up --build
  54
  55 To hot/live update CDB whilst it is running, use:
  56
  57         ./utils/reload.sh
  58
  59 This will only work with python code and templates, it won't update tasks or config.
  60
  61
  62 ## How-tos
  63
  64 ```sh
  65 # Hot/live reload (only works with FLASK_DEBUG=1)
  66 ./utils/reload.sh
  67
  68 # Cold update a running version of CDB with minimal downtime (production)
  69 ./utils/update.sh
  70
  71 # Enter docker
  72 ./utils/bash.sh
  73
  74 # Run migrations
  75 ./utils/run_migrations.sh
  76
  77 # Create new migration
  78 ./utils/create_migration.sh
  79 ```
  80
  81 ## Database
  82
  83
  84 ```mermaid
  85 classDiagram
  86
  87 User "1" --> "*" Package
  88 User --> UserEmailVerification
  89 User "1" --> "*" Notification
  90 Package "1" --> "*" Release
  91 Package "1" --> "*" Dependency
  92 Package "1" --> "*" Tag
  93 Package "1" --> "*" MetaPackage : provides
  94 Release --> MinetestVersion
  95 Package --> License
  96 Dependency --> Package
  97 Dependency --> MetaPackage
  98 MetaPackage "1" --> "*" Package
  99 Package "1" --> "*" Screenshot
 100 Package "1" --> "*" Thread
 101 Thread "1" --> "*" Reply
 102 Thread "1" --> "*" User : watchers
 103 User "1" --> "*" Thread
 104 User "1" --> "*" Reply
 105 User "1" --> "*" ForumTopic
 106
 107 User --> "0..1" EmailPreferences
 108 User "1" --> "*" APIToken
 109 APIToken --> Package
 110 ```