diff --git a/docs/api/configuration.md b/docs/api/configuration.md index e69de29..bb1db33 100644 --- a/docs/api/configuration.md +++ b/docs/api/configuration.md @@ -0,0 +1,38 @@ +# API configuration + +The API server stores all config keys in JSON format in the file `config.json` located under the project's root. +On this page you can find all config sections and keys that can be set. + +## database + +Configuration section where all database-related keys are stored. + +### name + +MongoDB database name. + +> Defaults to: `"garbage_api"` + +### host + +MongoDB database host. + +> Defaults to: `"127.0.0.1"` + +### port + +MongoDB database port. + +> Defaults to: `27017` + +### user + +MongoDB database user. Can be string or `null`. + +> Defaults to: `null` + +### password + +MongoDB database password. Can be string or `null`. + +> Defaults to: `null` diff --git a/docs/api/installation.md b/docs/api/installation.md index e69de29..f8b98ba 100644 --- a/docs/api/installation.md +++ b/docs/api/installation.md @@ -0,0 +1,125 @@ +# Installation + +## Requirements + +* [Git](https://git-scm.com) +* [MongoDB](https://www.mongodb.com) +* [Python 3.8+](https://www.python.org) + +## Installation process + +This manual assumes that your default Python interpreter is called `python` and is Python 3 of the compatible version. + +??? question "What Python interpreter do I use?" + + Python may have multiple instances installed on your machine. + On some Linux machines Python 2.7 is the default interpreter called `python` + and Python 3 is called `python3` or `python39`. + + You can check which Python version you use using following methods: + + === "Linux" + + Check which interpreter is used: + + ``` sh title="Shell" + which python + ``` + + and check the Python version: + + ``` sh title="Shell" + python -V + ``` + + You can also change default python as follows: + + ``` sh title="Shell" + sudo update-alternatives --config python + ``` + + === "Windows" + + Check which interpreters are available: + + ``` sh title="Terminal" + where python + ``` + + and check the Python version used by default: + + ``` sh title="Terminal" + python -V + ``` + + You can also change default python using [this guide](https://stackoverflow.com/a/68139696). + + Next, use the interpreter of choice instead of `python` during the installation: + + ``` shell title="Shell" + /usr/local/bin/python311 -m venv .venv + ``` + + Please note that after the activation of a virtual environment, interpreter you need + already has a correct alias and is called `python` regardless of the version. + +### Install Mongo + +Please follow the [official installation manual](https://www.mongodb.com/docs/manual/installation) for that. + +### Clone the source code + +``` sh +# Clone the repository +git clone https://git.end-play.xyz/GarbageReminder/API.git +# Then go the repository's directory +cd API +``` + +### Create virtual environment + +=== "Linux" + + Create virtual environment and activate it: + + ``` powershell title="Shell" + python -m pip install virtualenv + virtualenv .venv + .venv/bin/activate + ``` + +=== "Windows" + + Create virtual environment and activate it: + + ``` powershell title="Terminal" + python -m pip install virtualenv + virtualenv .venv + .venv\Scripts\Activate.ps1 + ``` + +### Install the requirements + +``` sh +python -m pip install -r requirements.txt +``` + +### Configure the API server + +This is a minimal configuration needed for the first start. For more config keys visit the [configuration](api/configuration.md) section in the documentation. + +1. Copy file example to the config file + + ``` sh + cp config_example.json config.json + ``` + +2. Open `config.json` with your favorite text editor +3. Change keys in the `"database"` section to match your MongoDB setup + +### Start the API server + +You can run your API by the following command: +`uvicorn main:app --host 127.0.0.1 --port 3000` + +Learn more about available uvicorn arguments using `uvicorn --help` diff --git a/docs/index.md b/docs/index.md index a6d7f43..c50151d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,27 @@ # Welcome to Garbage Reminder -This documentation is under development and is not finished yet. +Universal, easy to set up and maintain way to remind your family, your neighbors or your tenants about garbage collection. +Built with Python using FastAPI, Pyrogram, MkDocs Material and in the future also Pycord. + +## How it works + +The whole instance consist of an API and the clients. +We provide chatbots as clients. These bots provide the access to the data stored in the database of an API. + +## Why this exists + +After seeing that most cities and villages around only offer proprietary software/websites or even no digital information +about garbage collection at all, it was decided to develop an own solution to this problem by storing the data in a +database and then show the data the way it is helpful for the end-user. + +## Deployment + +Bare minimum installation requires a database and an API. Then you can use any way you like to connect to the API. +We provide Telegram bot and raw HTTP for that now, but Discord bot and CLI are planned too. + +Here is how the "normal" deployment process looks like: + +1. Install the requirements [[API](api/installation.md#requirements)/[Telegram](bot_telegram/installation.md#requirements)] +2. Install the API server [[Guide](api/installation.md)] +3. Install the client/bot of your linking [[Telegram](bot_telegram/installation.md)] +4. Fill the API/bot with the data [[API](api/feeding-data.md)/[Telegram](bot_telegram/feeding-data.md)] diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 1ef4420..82be0df 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -2,4 +2,7 @@ --md-primary-fg-color: #A9C217; --md-primary-fg-color--light: #A9C217; --md-primary-fg-color--dark: #A9C217; + --md-accent-fg-color: #bedd0e; + --md-accent-fg-color--light: #bedd0e; + --md-accent-fg-color--dark: #bedd0e; } \ No newline at end of file