🐙 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:
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.
- 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.
- 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).
- Clone this repository to your computer.
- Copy config template file (
src/config/config.template.js) tosrc/config/config.js.
cp src/config/config.template.js src/config/config.js
Note: you can safely commit
src/config/config.jsfile to a repository. This file does not store sensitive credentials - all config variables will be publicly available in the.jsfile 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.jscreated 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.
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
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.
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!
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.
- React via create-react-app.
- viz.js
- flowchart.js
- Firebase
- 15.09.2017 - "Open as .png" option
- 13.09.2017 - Initial release
Bartosz Olchówka / CTO @ LiveChat
This project is licensed under the MIT License - see the LICENSE file for details
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent