Skip to content

01 Setup (no Docker)

Jump to bottom
sec77 edited this page Jun 23, 2025 · 17 revisions

Setup

Put the content of the perlite directory from the latest release in your web root directory, your notes folder should resident as a subfolder of perlite.

Example:

/var/www/#

└── html
       ├── content.php
       ├── MyNotes <-- your Notes Folder
       ├── favicon.ico
       ├── helper.php
       ├── index.php
       ├── perlite.svg
       ├── settings.php
       └── vendor

Define your Notes Folder in Perlite

You need to define your vault (folder) name in perlite, you can do this via 1. a php environment variable or by 2. using the settings.php.

Option 1 Add this variable to your fpm config, usually located at /etc/php/8.4/fpm/pool.d/www.conf. Make sure to restart you php-fpm service after adding this.

env[NOTES_PATH] = MyNotes

Option 2 Adjust the settings.php

$rootDir = "MyNotes";

Adjust the Nginx Config

Starting with version 1.6, Perlite uses pretty URLs. The old ?link= syntax is still supported, but is no longer passed on to the frontend. To make direct links work in Perlite, you need to make some changes in the web server configuration. You can use this configuration as an example: perlite.conf. This also contains some security settings to prevent direct access to markdown or metadata files such as metadata.json.

The most important setting is the following:

    location / {
        try_files $uri $uri/ /index.php;
    }

this redirects any (file not found) path call to the index.php, which will translate the called path and retrieve the content of the file. If you are using Apache as Webserver, please take a look at this issue Hosting on Apache 2.4. You can also force the redirect via a .htaccess file.

if Perlite is not in the webroot directory, for example your URL is something like this https://myserver.com/perlite you need to adjust the config to the following and also define the path in the settings.php and perlite.js:

perlite.conf

    location /perlite {
        try_files $uri $uri/ /perlite/index.php;
    }

settings.php

$uriPath = "/perlite/";

.js/perlite.js

var uriPath = '/perlite/'

Obsidian Requirements

follow the Required Obsidian Settings to get your links and images working in perlite.

Graph Requirements

follow the Graph Setup to get the graph working in perlite.


Server Requirements

  • NGINX or Apache
  • PHP 7.4 or 8.X

also make sure you have installed the necessary PHP modules yaml_parse for the metadata (apt install php-yaml)


you can also follow this tutorial for a step by step solution: https://blog.nihilism.network/selfhosting/perlite/index.html but keep in mind that you need to adjust the webserver config to the above mentioned settings.

Clone this wiki locally