Table of Contents
- Logging In
- Installing Node.js & PM2
- Installing Raneto
- Further Configuration
- Adding Pages
- Adding Categories
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.
After entering your password (you can get it from the IT Web Services dashboard) you’ll be logged into your VPS.
Installing Node.js & PM2
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.
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.
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?
Using the Online Editor
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
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
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
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:
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.
Changing the Template
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.
Do you need help setting up this on your own service?
Please contact us and we’ll provide you the best possible quote!