~hristoast/mousikofidi

1a93cc798bd7d3691ac4fc11eb03d0e09923497e — Hristos N. Triantafillou a month ago 7f6f76b
A better quickstart, more improvements and corrections
1 files changed, 48 insertions(+), 13 deletions(-)

M setup.md
M setup.md => setup.md +48 -13
@@ 12,6 12,19 @@ Before running your own MousikóFídi instance, certain requirements must be sat

## Quickstart

If you just want to run MousikóFídi locally to check it out:

	# User install; Ensure $HOME/.local/bin is in your $PATH!
    pip3 install --user MousikoFidi

	mousikofidi --dev

Now, open `http://127.0.0.1:5000/` in a browser to use MousikóFídi.

## Server Quickstart

This section is a high-level look at what you need to do to run MousikóFídi on a server.

Open a terminal and follow the commands shown below:

	# First, ensure that the "python3-dev" and "python3-pip"


@@ 19,6 32,7 @@ Open a terminal and follow the commands shown below:
    # ... whatever the method is.
    sudo apt install python3-dev python3-pip
    sudo dnf install python3-devel python3-pip
    sudo pacman -S python3
    sudo xbps-install -Su python3-devel python3-pip

	# Create a new user to run MousikóFídi as


@@ 28,7 42,7 @@ Open a terminal and follow the commands shown below:
    sudo su - fidi

    # Install MousikóFídi
    python3 -m pip install --user MousikoFidi
    pip3 install --user MousikoFidi

    # Fix permissions
    chmod 0755 ~/.local


@@ 42,16 56,13 @@ Open a terminal and follow the commands shown below:
    # Adjust the config file as needed
    vi ~/.config/fidi/config.yml

    # Re-run MousikóFídi with your tweaked configs
    mousikofidi --dev

Now, open `http://127.0.0.1:5000/` in a browser to use MousikóFídi.
At this point, you are ready to go on to setting up [uWSGI](#configuring-uwsgi) and [Nginx](#configuring-nginx).

Read on for more detailed information about everything, including how to run MousikóFídi in production mode with [uWSGI](#configuring-uwsgi) and [Nginx](#configuring-nginx).
Continue to the next section for a more detailed breakdown of what is shown above.

## Installation

Although it is not strictly required, this guide covers running MousikóFídi as an unprivileged user.
Although it is not strictly required, this guide covers running MousikóFídi as its own unprivileged user.

### Creating the fidi user



@@ 64,18 75,35 @@ The home directory is specified as `/opt/fidi` to avoid any potential permission
From here, become the new user and verify it is usable:

    sudo su - fidi
    ls -lah

### Ensure `$PATH`

Before installing MousikóFídi we have to make sure that the install location is in the `fidi` user's `$PATH`. If you run this:

    sudo su - fidi
    echo $PATH

And don't see `/opt/fidi/.local/bin` in there, then do this:

    sudo su - fidi
    echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile
    source ~/.profile

Now you should be able to successfully run `mousikofidi --dev`.

### Installing MousikóFídi

    sudo su - fidi
    python3 -m pip install --user MousikoFidi
    pip3 install --user MousikoFidi

Note that the `--user` flag is used, which installs all packages under `fidi`'s home directory, eliminating the need for any superuser access.

Doing this puts all executables under `/opt/fidi/.local/bin`, so that path must be used or added to the `$PATH` variable.
Doing this puts all executables under `/opt/fidi/.local/bin`, so that path must be used or added to the `$PATH` variable as noted above.

Additionally, it will put static files under a local python library path.  Determine where this is like so:

    sudo su - fidi
    ls -d ~/.local/lib/python3.*/site-packages/mousikofidi/static

MousikóFídi should now be installed but not yet usable; a configuration file needs to be installed next.


@@ 84,6 112,7 @@ MousikóFídi should now be installed but not yet usable; a configuration file n

There's a good chance that installing MousikóFídi with `pip` will create directories with very restrictive permissions.  Run these commands to allow the web server user to read them:

    sudo su - fidi
    chmod 0755 ~/.local
    chmod 0755 ~/.local/lib
    chmod 0755 ~/.local/lib/python3.*


@@ 93,17 122,19 @@ There's a good chance that installing MousikóFídi with `pip` will create direc

Run MousikóFídi like this:

    sudo su - fidi
    mousikofidi --dev

The first time you run MousikóFídi, a config file will be generated at `$HOME/.config/fidi/config.yml`.  You can view the contents of this file [in the MousikóFídi source code](https://git.sr.ht/~hristoast/mousikofidi/tree/29ab6340d79bcf618032f6d35d7b85a8a7e3e11d/mousikofidi/mousikofidi.py#L45-58).

Open this file with a text editor to alter any values as desired:

    sudo su - fidi
    vi ~/.config/fidi/config.yml

See [the Config wiki page](https://man.sr.ht/~hristoast/mousikofidi/config.md) for more information.

Open `http://127.0.0.1:5000/` in a browser to use MousikóFídi.  You may need to re-login or re-source your shell profile for the `mousikofidi` to be found.
If running on your local machine, at this point you may open `http://127.0.0.1:5000/` in a browser to use MousikóFídi.

Read on for information about how to run MousikóFídi in production mode.



@@ 137,10 168,12 @@ This can be done quickly with `sed`:

Create that directory:

    sudo su - fidi
	mkdir ~/tmp

MousikóFídi can now be ran via `uwsgi` and the `mousikofidi` executable:

    sudo su - fidi
	mousikofidi --processes $(nproc)

Read on for how to access this via the Nginx HTTP server.


@@ 182,7 215,9 @@ Read on for a description of how to configure Nginx to read the `uwsgi` socket.

### The nginx configuration

Included with MousikóFídi is [an example Nginx configuration file](https://git.sr.ht/~hristoast/mousikofidi/tree/897ab601f793064307f7ce142cf5eb15598f6998/example/fidi-nginx.conf).  Copy this file to where nginx configs are kept:
Included with MousikóFídi is [an example Nginx configuration file](https://git.sr.ht/~hristoast/mousikofidi/tree/897ab601f793064307f7ce142cf5eb15598f6998/example/fidi-nginx.conf) that you may use as a base for your own setup.

Copy this file to where nginx configs are kept:

	curl -o fidi-nginx.conf https://git.sr.ht/~hristoast/mousikofidi/blob/master/example/fidi-nginx.conf
    sudo cp -iv fidi-nginx.conf /etc/nginx/sites-available/


@@ 208,9 243,8 @@ Some edits need to be made before this config will actually work:
        sudo su - fidi
        mkdir ~/ssl

* Create a password file that will be used for basic auth:
* Create a password file that will be used for basic auth (This requires the `apache2-utils` package on Debian/Ubuntu):

        # This requires the `apache2-utils` package on Debian/Ubuntu
        sudo su - fidi
        htpasswd -c /opt/fidi/.fidiauth YourFidiUserName
        chmod 0640 /opt/fidi/.fidiauth


@@ 219,6 253,7 @@ Some edits need to be made before this config will actually work:

* [This line](https://git.sr.ht/~hristoast/mousikofidi/tree/271d7bd9a1b4c5669d967c4a69efe97414331a1e/example/fidi-nginx.conf#L37) needs to point to where `pip` put the static files.  As noted above, this location can be determined with `ls`:

        sudo su - fidi
        ls -d ~/.local/lib/python3.*/site-packages/mousikofidi/static

Test the nginx configuration before reloading: