github/MIND
1
1
Fork 0
mirror of https://github.com/Casvt/MIND.git synced 2026-02-19 11:54:46 -05:00
Code Issues Packages Projects Releases Wiki Activity

Added base URL and locale docs, moved some things around

Browse Source
This commit is contained in:
CasVT
2023-07-03 16:03:50 +02:00
parent da286bd7d8
commit 155c51cc22
3 changed files with 62 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/installation.md
View File

@@ -6,8 +6,35 @@ NOTE: Make sure to set all time related settings (time, date, timezone, etc.) co
## Docker
### Database location
We first need to create a named volume, or a folder, to store the database file of MIND in.
=== "Docker CLI"
The command to get the docker container running can be found below. Replace the timezone value (`TZ=`) to the [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) of your timezone.
```bash
docker volume create mind-db
```
=== "Portainer"
- Open `Volumes`
- Click `Add Volume`
- Enter name matching the one you'll use in compose (`mind-db`, in the above provided command)
- Click `Create the volume`
- Open `Stacks`
- Create the stack with the named volume in it.
=== "Folder"
Linux standards suggest to put the database in `/opt/application_name`, as the `/opt` directory is where program options should be stored. In this case, you'd create the desired folder using the following command:
```bash
mkdir /opt/MIND/db
```
### Run the container
Now that we can store the database somewhere, we can get the container running.
=== "Docker CLI"
The command to get the docker container running can be found below. Replace the timezone value (`TZ=`) with the [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) of your timezone (value of `TZ identifier` on webpage).
```bash
docker run -d \
--name mind \
@@ -16,8 +43,9 @@ NOTE: Make sure to set all time related settings (time, date, timezone, etc.) co
-p 8080:8080 \
mrcas/mind:latest
```
=== "Docker Compose"
The contents of the `docker-compose.yml` file would look like below. Replace the timezone value (`TZ=`) to the [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) of your timezone.
The contents of the `docker-compose.yml` file would look like below. Replace the timezone value (`TZ=`) with the [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) of your timezone (value of `TZ identifier` on webpage).
```yml
version: '3.3'
services:
@@ -31,30 +59,15 @@ NOTE: Make sure to set all time related settings (time, date, timezone, etc.) co
- '8080:8080'
image: 'mrcas/mind:latest'
```
Now run the compose by running the following command in the root folder:
```bash
docker compose up -d
```
If you didn't name your docker volume `mind-db` (see [Database location](#database-location)), replace `mind-db` in the command with the name of your volume. If you created a folder, replace `mind-db` with `/opt/MIND/db` or the folder you want.
Information on how to change the port can be found on the [Setup After Installation page](setup_after_installation.md#port).
Using a named volume in docker requires you to create the volume before you can use it (see [Named Volumes](#named-volumes)).
### Named Volumes
=== "Docker CLI"
```bash
docker volume create mind-db
```
=== "Portainer"
- Open `Volumes`
- Click `Add Volume`
- Enter name matching the one you'll use in compose (`mind-db`, in the above provided command)
- Click `Create the volume`
- Open `Stacks`
- Create the stack with the named volume in it.
Both of these options will create a named volume that you can then use in the command above.
If you'd prefer to use a local folder on the host machine for storing config, Linux standards would suggest putting that in `/opt/application_name`, as the `/opt` directory is where program options should be stored.
In this case, you'd create the desired folder with something like `mkdir /opt/MIND/db`, and replace 'mind-db:/app/db' with '/opt/MIND/db:/app/db'.
## Manual Install
See below for installation instructions for your OS if you want to install it manually.
@@ -67,6 +80,7 @@ See below for installation instructions for your OS if you want to install it ma
python3 -m pip install -r requirements.txt
python3 MIND.py
```
=== "Windows"
1. Install python [in the Microsoft Store](https://www.microsoft.com/store/productId/9PJPW5LDXLZ5)
2. Install pip [using these instructions](https://www.liquidweb.com/kb/install-pip-windows/)
@@ -75,9 +89,9 @@ See below for installation instructions for your OS if you want to install it ma
5. With the folder open, right click and select `Open in Terminal`
6. Type the following command:
```bash
python3 -m pip install -r requirements.txt
python -m pip install -r requirements.txt
```
7. Type the following command:
```bash
python3 MIND.py
python MIND.py
```

12
docs/setup_after_installation.md
View File

@@ -15,10 +15,20 @@ The first thing to do is decide if you want to leave MIND running on the default
=== "Manual Install"
Inside the `MIND.py` file at the top, you can set the port via the `PORT` variable. Change it from `PORT = '8080'` to `PORT = '{PORT}'`, where `{PORT}` is the desired port (e.g. `PORT = '8009'`). Then restart the application.
## Base URL
If you want to set a base url (e.g. for a reverse proxy), go inside the `MIND.py` file and at the top, you can set the base URL via the `URL_PREFIX` variable. Change it from `URL_PREFIX = ''` to `URL_PREFIX = '/{PREFIX}'`, where `{PREFIX}` is the desired URL prefix (e.g. `URL_PREFIX = '/mind'`). Then restart the application.
## Creating an account
When accessing the web-ui, you'll be prompted to log in. Click on `Or create an account`, enter the desired username and password for the account and click `Create`. The account is created and can now be logged in with. The complete authentication process is local and no data is shared with any other service.
## Set your locale
In the settings, you can change your locale, so that the dates and times are displayed in the format used by your country.
## Add a notification service
A notification service is a way of sending a notification. For example an e-mail to a group of people or a PushBullet notification to a specific device. What the actual content of the notification is, is decided by the title and text of the reminder. The notification service only specifies in which way the title and text is sent. You set it up once, and then you can select it when creating a reminder. A notification service consists of a title (name) and an Apprise URL. See the [Apprise URL documentation](https://github.com/caronc/apprise#supported-notifications) to learn how to make a valid Apprise URL.
A notification service is a way of sending a notification. For example an e-mail to a group of people or a PushBullet notification to a specific device. What the actual content of the notification is, is decided by the title and text of the reminder. The notification service only specifies in which way the title and text is sent. You set it up once, and then you can select it when creating a reminder.
Go to the "Notification Services" tab in the web-ui and click the `+` button. A notification service consists of a title (name) and an Apprise URL. See the [Apprise URL documentation](https://github.com/caronc/apprise#supported-notifications) to learn how to make a valid Apprise URL.

18
project_management/generate_api_docs.py
View File

@@ -26,27 +26,34 @@ All endpoints have the `{api_prefix}` prefix. That means, for example, that `/au
## Authentication
Authentication is done using an API key. To log in, make a POST request to the [`/api/auth/login`](#authlogin) endpoint. You'll receive an API key, which you can then use in your requests to authenticate. Supply it as a url parameter with the key `api_key`. This API key is valid for one hour, after which the key expires, any further requests return 401 'APIKeyExpired' and you are required to log in again. If no `api_key` is supplied or it is invalid, 401 `APIKeyInvalid` is returned.
Authentication is done using an API key.
To log in, make a POST request to the [`{api_prefix}/auth/login`](#authlogin) endpoint.
You'll receive an API key, which you can then use in your requests to authenticate.
Supply it via the url parameter `api_key`.
This API key is valid for one hour after which the key expires, any further requests return 401 'APIKeyExpired' and you are required to log in again.
If no `api_key` is supplied or it is invalid, 401 `APIKeyInvalid` is returned.
For example:
```bash
curl -sSL 'http://192.168.2.15:8080/api/reminders?api_key=ABCDEFG'
curl -sSL 'http://192.168.2.15:8080{api_prefix}/reminders?api_key=ABCDEFG'
```
## Supplying data
Often, data needs to be supplied with a request. If the parameters need to be supplied via `url`, add them to the url as url parameters. If the parameters need to be supplied via `body`, add them to the body as a json object and supply the `Content-Type: application/json` header.
Often, data needs to be supplied with a request.
If the parameters need to be supplied via `url`, add them to the url as url parameters.
If the parameters need to be supplied via `body`, add them to the body as a json object and supply the `Content-Type: application/json` header.
For example:
```bash
# URL parameter
curl -sSL 'http://192.168.2.15:8080/api/reminders/search?api_key=ABCDEFG&query=Fountain&sort_by=time_reversed'
curl -sSL 'http://192.168.2.15:8080{api_prefix}/reminders/search?api_key=ABCDEFG&query=Fountain&sort_by=time_reversed'
# Body parameter
curl -sSLX POST \\
-H 'Content-Type: application/json' \\
-d '{{"title": "Test service", "url": "test://fake/url"}}' \\
'http://192.168.2.15:8080/api/notificationservices?api_key=ABCDEFG'
'http://192.168.2.15:8080{api_prefix}/notificationservices?api_key=ABCDEFG'
```
## Endpoints
@@ -125,4 +132,3 @@ else:
run(["git", "add", _folder_path('docs', 'api.md')])
run(["git", "commit", "-m", "Updated API docs"])
run(["git", "push"])