a wiki service
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Forest Belton e9d8383d02 Create git repository if it does not exist 1 week ago
js Add margin after article title input 1 week ago
migrations Add table for categories 2 weeks ago
scripts Add table for categories 2 weeks ago
src Create git repository if it does not exist 1 week ago
.dockerignore Implement random article page and fetch articles 1 week ago
.env Persist articles to filesystem 2 weeks ago
.gitattributes Set up web server 2 weeks ago
.gitignore Ignore VS Code directory 1 week ago
Cargo.lock Apply patch files for new articles 1 week ago
Cargo.toml Apply patch files for new articles 1 week ago
Dockerfile Set up Dockerfile for service 2 weeks ago
LICENSE Add LICENSE file 2 weeks ago
README.md Add section for manual deploys 1 week ago
diesel.toml Integrate Diesel 2 weeks ago
docker-compose.yml Implement random article page and fetch articles 1 week ago

README.md

oxidoc

Oxidoc is a wiki service designed for simplicity and ease of use. The service consists of several components:

  • Web UI
  • Rust API service
  • Postgres (wiki metadata)
  • Git (wiki data)

Keeping track of the wiki data within a git repository has several benefits, but mainly it is due to concurrency. By using git, there is no need to worry about atomicity when updating an article, and failed merges produce output that can be easily consumed by the API.

Postgres exists to keep track of data not stored within the articles themselves. This includes creation & edit times, user information, and other related fields.

Setup

Oxidoc can be deployed in two ways: either through using a collection of Docker containers or by a more manual approach. While this section outlines both methods, it is preferable to use Docker due to the simplicity of this approach.

Using Docker

First, make sure you have Docker installed. Then run the following commands from the project directory:

$ docker-compose build
$ docker-compose up

Once these commands complete, the service should be fully operational and listening for new HTTP connections on the default port (60000).

Manually

Manual builds require two steps: one for the frontend and one for the API. If you are deploying the service manually, make sure you have a Postgres instance configured to accept connections and have updated the DATABASE_URL configuration value.

Frontend

Make sure you have a recent copy of Node.js installed. If you don’t have Node.js, install nvm and install the latest stable version. Then, to build the project:

$ npm install
$ npm run build

By default, the API will serve static files from js/public, so nothing else needs to be done.

API

Make sure you have a recent copy of Rust installed. If you don’t have Rust, install rustup and install the latest stable version. Then, to build the project:

$ cargo build

After the project is successfully built, the API can be started via:

$ cargo run

Configuration

Since Oxidoc is a twelve-factor app, configuration occurs mainly through environment variables. The following table represents all of the available options along with a brief description of their meaning:

Name Description
IFACE The network interface to listen for connections on
PORT The network port to listen on
DATABASE_URL A Diesel-compatible URL that refers to the Postgres database
REPOSITORY_DIR The location of the backing Git repository

These values can also be updated in the .env file rather than passed through the environment. An environment variable will always take precedence over the value defined in .env.