117 lines
6.2 KiB
Markdown
117 lines
6.2 KiB
Markdown
|
# Private Grav Plugin
|
||
|
|
|
||
|
|
> New version is [Private Site](https://github.com/Diyzzuf/grav-plugin-private-site) **(beta stage, not for production. Need users to test this plugin)**
|
||
|
|
|
||
|
|
`Private` is a [Grav](http://github.com/getgrav/grav) Plugin.
|
||
|
|
|
||
|
|
Private provides an authentication form to keep your entire Grav site or part of it private from the general public.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
# Installation
|
||
|
|
|
||
|
|
Installing the Private plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method allows you to do so by downloading a zip file to place in the Grav plugins directory.
|
||
|
|
|
||
|
|
## GPM Installation (Preferred)
|
||
|
|
|
||
|
|
The simplest way to install this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm) through your system's Terminal (also called the command line). From the root of your Grav install type:
|
||
|
|
|
||
|
|
bin/gpm install private
|
||
|
|
|
||
|
|
This will install the Private plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/private`.
|
||
|
|
|
||
|
|
## Manual Installation
|
||
|
|
|
||
|
|
To install this plugin, just download the zip version of this repository and unzip it under `/your/site/grav/user/plugins`. Then, rename the folder to `private`. You can find these files either on [GitHub](https://github.com/diyzzuf/grav-plugin-private) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
||
|
|
|
||
|
|
You should now have all the plugin files under
|
||
|
|
|
||
|
|
/your/site/grav/user/plugins/private
|
||
|
|
|
||
|
|
|
||
|
|
# Usage
|
||
|
|
|
||
|
|
By default, the password is `password`, username is **not** needed and Grav is **fully private**.
|
||
|
|
|
||
|
|
To customize this parameters (and more), you first need to create an override config. To do so, create the folder `user/config/plugins` (if it doesn't exist already) and copy the [private.yaml](private.yaml) config file in there and then make your edits.
|
||
|
|
|
||
|
|
## Recommended changes to be made to ensure your site is secure (See Options section below)
|
||
|
|
1. **Change** the default password in your `user/config/plugins/private.yaml`
|
||
|
|
2. **Change** the default security salt in your `user/config/plugins/private.yaml`
|
||
|
|
3. **Customize** your privacy rules
|
||
|
|
|
||
|
|
# Options
|
||
|
|
|
||
|
|
###### Plugin
|
||
|
|
Enable or Disable the entire plugin (default: `true`).
|
||
|
|
|
||
|
|
enabled: (true|false)
|
||
|
|
|
||
|
|
###### Routing
|
||
|
|
Routes of login and logout. You can customize it by replacing value (e.g: login: "/admin" for "mywebsite.com/admin" )
|
||
|
|
|
||
|
|
routes:
|
||
|
|
login: "/login"
|
||
|
|
logout: "/logout"
|
||
|
|
|
||
|
|
###### Security Salt
|
||
|
|
Security Salt for session. **IT MUST BE AN ALPHANUMERIC CHAR** You can go to this [generator](http://www.sethcardoza.com/tools/random-password-generator/) for your own. [temporary cached version](http://webcache.googleusercontent.com/search?q=cache:www.sethcardoza.com/tools/random-password-generator/)
|
||
|
|
|
||
|
|
session_ss: random_value
|
||
|
|
|
||
|
|
###### Private Site
|
||
|
|
If `true`, the entire site is private. If false, then Private can be enabled on a page by page basis by using the `private_tag` ( See after ) (default: `true`)
|
||
|
|
|
||
|
|
private_site: (true|false)
|
||
|
|
|
||
|
|
###### Private Tag
|
||
|
|
If the private_site value is `false`, you will need to add the `private_tag` on your private page. (default: `hidden`)
|
||
|
|
See [Grav Taxonomy](http://learn.getgrav.org/content/taxonomy) for more information.
|
||
|
|
|
||
|
|
private_tag: hidden
|
||
|
|
|
||
|
|
###### Username on login page
|
||
|
|
Enable (`true`) or Disable (`false`) the username field on the private page's login form. (default: `false`)
|
||
|
|
> Note : If you disable the username, you need to **keep** `no_user` username in the `users` parameters.
|
||
|
|
enable_username: (true|false)
|
||
|
|
|
||
|
|
###### Users list
|
||
|
|
List of users. For adding user, just create a new line **keeping the identation**. (default password: `password`)
|
||
|
|
> Note : If enable_username is `false`, you must not delete the `no_user` user in the list.
|
||
|
|
|
||
|
|
>> Note : The password **MUST BE** a SHA1 value. For quick checking see [SHA1 Online](http://www.sha1-online.com) to generate your SHA1 password. But it is adwised to generate it locally as http and any transmission is not as secure as no transmission at all. Use command: ` echo -n "yourpassword" | sha1sum`. You can remove it thereafter from bash history with `history -d 1234` and sourcing the ~/bashrc.
|
||
|
|
|
||
|
|
users:
|
||
|
|
no_user : sha1_password
|
||
|
|
|
||
|
|
###### Text
|
||
|
|
This section allows you to change the text which will appear on the login form on Private enabled pages.
|
||
|
|
|
||
|
|
fields:
|
||
|
|
username:
|
||
|
|
label: "Username"
|
||
|
|
placeholder: "Enter your username"
|
||
|
|
|
||
|
|
# Updating
|
||
|
|
|
||
|
|
As development for the Private plugin continues, new versions may become available that add additional features and functionality, improve compatibility with newer Grav releases, and generally provide a better user experience. Updating Private is easy, and can be done through Grav's GPM system, as well as manually.
|
||
|
|
|
||
|
|
## GPM Update (Preferred)
|
||
|
|
|
||
|
|
The simplest way to update this plugin is via the [Grav Package Manager (GPM)](http://learn.getgrav.org/advanced/grav-gpm). You can do this by navigating to the root directory of your Grav install using your system's Terminal (also called command line) and typing the following:
|
||
|
|
|
||
|
|
bin/gpm update private
|
||
|
|
|
||
|
|
This command will check your Grav install to see if your Private plugin is due for an update. If a newer release is found, you will be asked whether or not you wish to update. To continue, type `y` and hit enter. The plugin will automatically update and clear Grav's cache.
|
||
|
|
|
||
|
|
## Manual Update
|
||
|
|
|
||
|
|
Manually updating Private is pretty simple. Here is what you will need to do to get this done:
|
||
|
|
|
||
|
|
* Delete the `your/site/user/plugins/private` directory.
|
||
|
|
* Download the new version of the Private plugin from either [GitHub](https://github.com/diyzzuf/grav-plugin-private) or [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
|
||
|
|
* Unzip the zip file in `your/site/user/plugins` and rename the resulting folder to `private`.
|
||
|
|
* Clear the Grav cache. The simplest way to do this is by going to the root Grav directory in terminal and typing `bin/grav clear-cache`.
|
||
|
|
|
||
|
|
> Note: Any changes you have made to any of the files listed under this directory will also be removed and replaced by the new set. Any files located elsewhere (for example a YAML settings file placed in `user/config/plugins`) will remain intact.
|