From 77efd3be8947a16c6976cd762757d8f566f295ee Mon Sep 17 00:00:00 2001 From: profitroll Date: Mon, 13 Mar 2023 13:00:47 +0100 Subject: [PATCH] Added README --- README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d0e5f1a --- /dev/null +++ b/README.md @@ -0,0 +1,99 @@ +

Photos API

+ +

+License: GPL +Code style: black +

+ +Small and simple API server for saving photos and videos. + +## Dependencies + +* [Python 3.7+](https://www.python.org) (3.9+ recommended) +* [MongoDB](https://www.mongodb.com) +* [exiftool](https://exiftool.org) +* [jpegoptim](https://github.com/tjko/jpegoptim) +* [optipng](https://optipng.sourceforge.net) + +## Installation + +First you need to have a Python interpreter, MongoDB and optionally git. You can also ignore git and simply download source code, should also work fine. After that you're ready to go. + +> In this README I assume that you're using default python in your +> system and your system's PATH contains it. If your default python +> is `python3` or for example `/home/user/.local/bin/python3.9` - use it instead. + +1. Install Mongo: + + Please follow [official installation manual](https://www.mongodb.com/docs/manual/installation) for that. + +2. Download Photos API: + + 1. `git clone https://git.end-play.xyz/profitroll/PhotosAPI.git` (if you're using git) + 2. `cd PhotosAPI` + +3. Create virtual environment [Optional yet recommended]: + + 1. Install virtualenv module: `pip install virtualenv` + 2. Create venv: `python -m venv env` + 3. Activate it using `source venv/bin/activate` on Linux, `venv\Scripts\activate.bat` in CMD or `venv\Scripts\Activate.ps1` in PowerShell. + +4. Install project's dependencies: + + `python -m pip install -r requirements.txt` + +5. Configure your API: + + 1. Copy file `config_example.json` to `config.json` + 2. Open `config.json` using your favorite text editor. For example `nano config.json` + 3. Change `"database"` keys to match your MongoDB setup + 4. Change `"external_address"` to the ip/http address you may get in responses. By default it's `"localhost"`. This is extremely useful when running behind reverse-proxy. + + After configuring everything listed above your API will be able to boot, however further configuration can be done. You can read about it in [repository's wiki](https://git.end-play.xyz/profitroll/PhotosAPI/wiki/Configuration). There's no need to focus on that now, it makes more sense to configure it afterwards. + +6. Start your API: + + You can run your API by the following command: + `uvicorn photos_api:app --host 127.0.0.1 --port 8054` + + Learn more about available uvicorn arguments using `uvicorn --help` + +## Using as a service + +It's a good practice to use your API as a systemd service on Linux. Here's a quick overview how that can be done. + +1. Create user and move your API + + You don't always need to do so, but that's a cleaner way to deploy a service. + + 1. Create service user `photosapi` using `sudo useradd -r -U photosapi` + 2. Assuming you are still in directory `PhotosAPI`, use `cd ..` to go up a level and then move your API to the distinguished folder. For example, `/opt/`: `sudo mv ./PhotosAPI /opt/` + 3. Make your user and its group own their directory using `sudo chown -R photosapi:photosapi /opt/PhotosAPI` + +2. Configure service + + Here's an example service file for PhotosAPI that is using virtual environment: + + ```systemd + [Unit] + Description=Photos API + After=network.target mongod.service + Wants=network-online.target mongod.service + + [Service] + Restart=always + Type=simple + ExecStart=/bin/bash -c 'source venv/bin/activate && venv/bin/uvicorn photos_api:app --port 8054' + WorkingDirectory=/opt/PhotosAPI + User=photosapi + Group=photosapi + + [Install] + WantedBy=multi-user.target + ``` + + 1. Create a service by pasting code above into `/etc/systemd/system/photos-api.service` + 2. Enable your service to start on system boot using `sudo systemctl enable photos-api.service` + 3. Start your service now using `sudo systemctl start photos-api.service` + 4. Check if it's running using `sudo systemctl status photos-api.service` + 5. If something goes wrong - check API's logs using `sudo journalctl -u photos-api.service`