Placeholders and README #2

Merged
profitroll merged 4 commits from dev into main 2024-05-14 00:43:12 +03:00
4 changed files with 191 additions and 1 deletions
Showing only changes of commit 7c5dd326bd - Show all commits

View File

@ -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`

View File

@ -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`

View File

@ -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)]

View File

@ -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;
}