This article is outdated and may not work correctly for current operating systems or software.
Raneto is a free and open-source knowledge base, built on Node.js that is easy to setup and use, as well as easy to administrate. Categories and pages are written in Markdown, which makes it easy to edit. If Markdown isn't your thing, Raneto also allows you to use HTML.
A VPS with Ubuntu 17.10 installed.
SSH access to your VPS.
Basic understanding of the Linux terminal.
First, we need to login to our server using SSH. To do this, open up your favorite SSH client.
ssh root@SERVER_IP
After entering your password (you can get it from the Vultr dashboard) you'll be logged into your VPS.
Raneto runs on Node.js, a javascript runtime and framework. In this tutorial, we'll be using Node.js v8 because of its long-term support. Start the installation by typing the following command.
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
After this script has finished running, you can run the main installation.
sudo apt-get install -y nodejs
Once this installer has finished, you will have an up to date copy of Node.js installed on your VPS. Next, we are going to install PM2, a process manager for Node.js that makes running Raneto (and many other Node.js applications) easier.
npm install pm2 -g
We've now got all the software we need to install Raneto.
We are going to use Git to clone the Raneto repository to our server.
git clone https://github.com/gilbitron/Raneto.git
This will create a folder called Raneto. Enter the folder.
cd Raneto
Install NPM.
npm install
Run Gulp by typing the following.
npm run gulp
Once Gulp has finished running, we can start our application using one of the two following commands.
npm start
# or
npm example/server.js
You will now be able to access your new Raneto installation by navigating to SERVER_IP:3000. The rest of this tutorial will teach you how to further configure Raneto, make new pages, add categories, adjust sorting, add a custom homepage and edit the template.
You now have a default Raneto installation hosted on your VPS. Before you start doing anything else, I suggest that you make a few changes to the default config and setup.
Let's take a look at config.default.js, which is located in the example folder. This config file is quite long, but please don't be overwhelmed, as it's heavily commented. Here are the properties you should edit:
site_title - Change this to your website title.
base_url - This should be set to your site's URL. It can be used as a variable when editing pages.
support_email - Change this to a valid email. It will show in the site's footer.
copyright - Footer text.
analytics - Add a Google Analytics tracking code here.
allow_editing - Do you want to be able to edit files using the web editor?
authentication_for_read - Do you want people to log in to view the website?
credentials - Add users here if login is enabled.
locale - Language.
datetime_format - Format of the date and time.
home_meta - Edit this to change your homepage's meta information.
table_of_content - Should Raneto display a table of contents?
Raneto comes with an easy to use online interface for managing pages, categories and more. While it doesn't allow you to do everything, it certainly is helpful if you need to make a quick edit on the go.
You can access it by enabling the setting in config.default.js (as mentioned above) and then visiting your VPS and clicking the login button in the top right corner. Enter your username and password (you can change these in config.default.js) and click login. Simply click on the page you need to edit, click the Actions drop-down and choose the action you want to complete. You can add pages by pressing the + button next to the category name, and you can create categories using the input field in the top left-hand corner.
Adding pages is as simple as creating a new Markdown (.md) document in the example/content folder.
Once you've created a new Markdown file, it's important that you add some basic information to the top of the file. Open the file in your favourite text editor. We need to add the following to the top of the file.
/*
Title: Enter your page title here, if none is added, the file-name will be used
Description: Enter your page's description here (for search engines and the site search feature)
ShowOnHome: true/false
*/
If you need to, you can also use the following variables in your pages:
%base_url% - This allows you to mention the URL of your website.
%image_url% - This allows you to get the base URL of your image directory.
You can add categories to your knowledge base easily. Just create a new folder in the example/content directory and put the pages you want to be in that category in that folder. For example, say we wanted a category called help with pages called contact, help-me and awesome. The files would look like this:
/example/content/help/contact.md
/example/content/help/help-me.md
/example/content/help/awesome.md
You can add as many sub-folders as you would like inside of categories.
Categories can also have meta information. Create a file called meta in the category folder. The following attributes are supported (all optional):
Title - Overrides title based on folder name.
Sort - Allows you to sort the order of categories, works the same way as sorting pages.
ShowOnHome - true/false.
If you want to add a custom homepage, all you need to do is add a markdown file called index.md to your example/content folder.
Raneto automatically sorts pages alphabetically, but you can apply a manual sort by adding a Sort item to the page meta. The value of sort must be an integer, for example:
Sort: 7
This page would now appear before pages with a sort value of 8 or more, but after pages with a value of 6 or less.
If you're familiar with HTML or CSS, you can easily change the look of your Raneto installation. Raneto uses Handlebars, a JavaScript templating language, that modularizes HTML editing. You can find the theme files in the themes/default folder. If you'd like more information on editing Renato templates, you can visit their help section. Once you've finished editing the template, make sure that you restart the application.