Skip to content

Latest commit

 

History

History
157 lines (115 loc) · 5.37 KB

INSTALL.md

File metadata and controls

157 lines (115 loc) · 5.37 KB

PiNanas Installation procedure

Requirements

Hardware

PiNanas will need a linux-based host, with:

  • 32 GB free disk space
  • 4 GB RAM, 8GB suggested
  • An access to Internet
  • Optionnally: a GPU suited to your needs (video transcoding & playing)

Software

During installation or operation, PiNanas requires:

  • GNU utils
  • docker and docker-compose
  • a wildcard (sub)domain name (e.g. *.home.example.com); read How to get a domain name? for more information.

Operating Systems

Have been tested: Debian, Ubuntu, Raspbian. PiNanas is expected to be compatible with a wide range of linux-based OS. Please do try new ones and report your findings.

Architectures

Both amd64 and arm are supported. Please report any findings regarding a specific version of amd64 or arm.

Download

Download

Direct download

Go and download our latest release Source code. Unzip the content of pinanas-$version/ anywhere on your PiNanas host. The following will assume you unzipped it in /path/to/pinanas.

Via git

From your PiNanas host, anywhere:

git clone --depth 1 --branch master https://github.com/yscialom/pinanas.git

The following will assume you clonned it in /path/to/pinanas.

User

You are free to run PiNanas with any user with:

  • rights on the docker daemon, and
  • read rights on the /path/to/pinanas directory. root is a possibility, although nor recommended.

For instance, create a pinanas user:

sudo useradd --groups docker --system pinanas

PiNanas installation directory

Create the installation directory for PiNanas. The following will assume it is /opt/pinanas.

sudo mkdir -p /opt/pinanas
sudo chown pinanas:pinanas /opt/pinanas

Settings

Define your settings

In the instalation directory, create a file settings.yaml from src/configure/settings.yaml.sample and fill in all mandatory values:

cd /opt/pinanas
cp /path/to/pinanas/src/settings.yaml.sample settings.yaml
chmod 600 settings.yaml # contains passwords
nano settings.yaml

Save and exit.

DNS Provider

PiNanas needs delegation on your domain name. To this end, you must create and fill in the appropriate variables to PiNanas. Read DNS Provider Variables for a complete guide.

Special care needed on settings.yaml

This file is both secret and precious. It contains passwords to both PiNanas administration and to external services. As such, it must be kept private, only readable to user having administration rights on the PiNanas host, and the pinanas user itself. If you run PiNanas on a disposable virtual machine, make a copy of settings.yaml and store it properly on a second device.

Ideally, settings.yaml is built upon deployment and secrets are kept by a dedicated tool.

Install

From your installation directory, run src/installer/install.sh:

cd /opt/pinanas
/path/to/pinanas/src/installer/install.sh

If you made important changes to settings.yaml and want to regenerate PiNanas, run with --force:

cd /opt/pinanas
/path/to/pinanas/src/installer/install.sh --force

Your installation is now complete.

Start

From your installation directory, run docker-compose up -d:

cd /opt/pinanas
docker-compose up -d

First Start

The first start of PiNanas can be slow, especially on low-end hardware. To better monitor it, you have:

  • /path/to/pinanas/test/wait-for-containers.sh: this script gives you information on containers, their status and health.
  • Traefik dashboard: go to https://traefik-dashboard.home.example.com (replace home.example.com with your actual domain). This dashboard will help you troubleshoot missing services, routers, ...
  • Netdata: go to https://resources.home.example.com (replace home.example.com with your actual domain). This monitoring tool will help you follow hardware and software resources consumption on your PiNanas host.

Setting up your personnal dashboard

Heimdall has been selected as PiNanas dashboard. It is a simple and great page to access and quicky check the status of all of PiNanas services. Go to https://apps.home.example.com (replace home.example.com with your actual domain) and click the Haimdall Application List button button and add your applications. You can find their urls on Traefik dashboard (https://traefik-dashboard.home.example.com).

Sign in with Authelia

When possible, we have set services to use Authelia as its authentification manager. Some tools, like Nextcloud or Jellyfin, allow authentification by Authelia or internally. If possible, always use Authelia for a fully secured and centralized authentification system.

Some services require a two-factor authentification (2FA). To access to those tool, set up Authelia 2FA. Read Authelia — One Time Password for a complete guide on how to setup your second-factor authentification.