Octopus

🐙 Octopus is a server-less, easy-to-setup internal wiki page with built-in software diagrams support. It uses Markdown for writing content and enhances it with Graphviz and flowchart.js diagrams for easy software documentation.

Here's a default wiki page:

Technology

Octopus is a JAMstack app that uses Google Firebase as its backend. You do not need a web server (such as Apache) or a database (like MySQL) to have it up and running. You can deploy the app to a CDN for free using Netlify.

With Octopus, you can:

require users to be signed in to read or edit the wiki (supported providers: Google, GitHub, Email/Password, Twitter and Phone),
create access rules for reading and editing (restrict particular users or auth domains),
host wiki page under a custom domain.

Features

create new wiki pages with Markdown language,
edit menu (using Markdown) to easily link to wiki pages,
include Graphviz and flowchart.js diagrams inside your Markdown content,
see who is currently reading your wiki articles,
adjust your Wiki front-end with React (create-react-app).

Example system diagram

Page editing with Markdown

Installation

Clone this repository to your computer.
Copy config template file (src/config/config.template.js) to src/config/config.js.

cp src/config/config.template.js src/config/config.js

Note: you can safely commit src/config/config.js file to a repository. This file does not store sensitive credentials - all config variables will be publicly available in the .js file anyway.

Create a new Firebase project here: https://firebase.google.com/
Pick "Add Firebase to your web app" and copy the config to src/config/config.js created in step 2.

In Firebase Console, go to Authentication > Sign-in method, choose a provider and enable it. Octopus has been tested with Google and GitHub providers.

Still in Authentication > Sign-in method section, add the domain that will host your app to Authorized Domains list.

Build the app:

npm install
npm run build

Deploy the build/ directory to your webserver.

Server-less deployment

You can skip hosting the app on your webserver (step 8 from installation guide above). All you need is to deploy the app to a cloud-based CDN provider.

We recommend using Netlify.

It will automatically deploy your forked Octopus GitHub repo to production after each commit. It will also prepare a ready-to-use URL that all your users can access immediately. Later on, you can set up a custom domain to make it look more professional.

Note: when deploying Octopus via Netlify, fill in the following details in the setup wizard:

Build command: npm run build
Publish directory: build

Security

By default, any user can view and edit your wiki page. Probably this is not what you expect!

To make your content accessible only to your company, go to Firebase Console > Database > Rules and restrict who can read and edit your wiki page.

Here's an example rule if you use Google sign-in provider and your company email address ends with @livechatinc.com:

{
  "rules": {
    ".read": "auth.token.email.endsWith('@livechatinc.com')",
    ".write": "auth.token.email.endsWith('@livechatinc.com')"
  }
}

You can read more about possible security rules in Realtime Database Rules documentation.

Using Octopus

Octopus is designed to be very easy to use.

To create a new page, just enter the URL you wish to create, for example: https://<your-octopus-domain>/test/new-page. If such page has not been created yet, you will see the following screen:

When you click "Create this page", new page will be created and filled in with default content, ready to edit:

Once the page is ready, you can easily include it in the menu:

That's it. Send all your teammates link to Octopus and they're ready to contribute!

Project background

Why did we build Octopus?

We've struggled with finding an easy-to-use software for documenting internal systems at LiveChat.

We wanted it to be easy to contribute for non-technical people and include easily editable software diagrams. We couldn't find a satisfying product, so we've built one.

Built with

Changelog

15.09.2017 - "Open as .png" option
13.09.2017 - Initial release

Authors

Bartosz Olchówka / CTO @ LiveChat

License

This project is licensed under the MIT License - see the LICENSE file for details

livechat / octopus