Oddmuse 6

This file is for the people wanting to download and install Oddmuse 6.

This is Oddmuse based on Raku and Cro.

If you're a developer, see the to do list.

If you're curious, see the feature list.

Table of Contents

• Quickstart
• Development
• Bugs
• Test
• Configuration
  • Changes
  • Resources
  • Images and CSS
  • Templates
  • Wiki
  • Example: Changing the CSS
  • Spam Protection
• Hosting Multiple Wikis
• Docker

Quickstart

Install Cro:

zef install --/test cro

Install Oddmuse 6:

zef install Oddmuse6

Create a new application by start with a stub and accepting all the defaults:

cro stub http test test

This creates a service called "test" in a directory called test. If you accept all the defaults, you'll get a service doing HTTP 1.1. Good enough for us!

Now edit test/services.p6 and replace use Routes with use Oddmuse::Routes.

You can delete the test/lib/Routes.pm6 which cro stub generated for you.

Your default wiki directory is test/wiki, so we need to tell cro to ignore it. If you don't, you'll confuse cro to no end as soon as you start editing files! Add the following section to your in test/.cro.yml file:

ignore:
  - wiki/

Run it:

cd test
cro run

Check it out by visiting http://localhost:20000. Your wiki is ready! 🙃

Let's configure it by setting an environment variable. More on this below. Replace the empty environment section in test/.cro.yml with the following and restart cro:

env:
  - name: ODDMUSE_MENU
    value: Home, Changes, About

And now you have a link to the About page. Follow the link and click the create it link. Write the following into the text area and click the Save button:

# About

This is my page.

Your first edit! 🎉

In order to make it public, you'll need to set two environment variables. Each cro service gets to environment variables that determine its host and its port. Their names depend on the name you provided when you called cro stub. If you called it test like I did in the example above, the two environment variables you need are called TEST_HOST and TEST_PORT. Feel free to change them in service.p6 and .cro.yml, though.

Development

Get the sources:

git clone https://alexschroeder.ch/cgit/oddmuse6

To run it, you need to install the dependencies:

cd oddmuse6
zef install --depsonly .

Then start the service:

cro run

This should start the wiki on http://localhost:20000/ and its data is saved in the wiki directory.

Bleeding Edge

If you installed a regular version of the wiki and now you want to switch to the code in your working directory, use the following in your working directory. It tests and installs the current version, and its dependencies.

zef install --force-install .

Bugs

🔥 When installing dependencies using zef as shown, you could be running into an OpenSSL issue even if you have the correct development libraries installed. On Debian, you need libssl-dev but apparently versions 1.1.0f and 1.1.0g won't work. See issue #34. You could decide to ignore SSL support and opt to have a web server act as a proxy which provides SSL. That's what I intend to do. In which case there is a terrible workaround available: run zef install --force-test IO::Socket::Async::SSL before you zef install Oddmuse6.

🔥 Every now and then I run into the error This type (NQPMu) does not support associative operations while I'm working on the code. As it turns out, rm -rf lib/.precomp solves this issue. You'll be doing this a lot until issue #2294 gets fixed.

🔥 When I ran into the error Type check failed in binding $high; expected Any but got Mu when computing a diff I found issue #12 for Algorithm::Diff. It's supposed to be fixed, now. One way to work around it is to check it out and install it from source:

git clone https://github.com/Takadonet/Algorithm--Diff
cd Algorithm--Diff
zef install --force-install .

Test

The Makefile has a test target. Use the jobs environment variable to control how many jobs run in parallel. The default is 4.

jobs=1 make test

Running tests create test data directories (test-nnnn). This allows us to run multiple tests in parallel. The directories are kept around for developers to inspect in case something went wrong. Eventually, you'll need to clean these up:

make clean

To run just one suite of tests:

make t/keep.t

This also shows you the data directory it uses:

Using test-1288

Configuration

If you look at the oddmuse/.cro.yml file you'll find a section with environment variables with which to configure the wiki.

Let's talk about these, first:

• ODDMUSE_STORAGE is the class handling your storage requirements. The default is Storage::File which stores everything in plain text files. We'd love to add more!

• ODDMUSE_WIKI is the location of your wiki. If you are using Storage::File (the default), then this refers to your wiki directory. Its default value is wiki. That's the same directory where this README.md is.

• ODDMUSE_MENU is a comma separated list of pages for the main menu. The default is Home, Changes, About. That also means that none of the pages in the menu may contain a comma.

Changes

One page name is special: viewing this page lists recent changes on the wiki instead of showing the page itself. By default, this page is called "Changes". It's name is stored in an environment variable:

• ODDMUSE_CHANGES is the page which acts as an alias for the /changes route. The default is Changes.

This means that you cannot edit the Changes page: it's content is inaccessible as the automatic list of recent changes is displayed instead.

Don't forget to change the changes.sp6 template if you change the name of this page.

Here's an example of how to have a page called "Updates":

1. Set the ODDMUSE_MENU environment variable to Home, Updates, About. This makes sure that "Updates" shows up in the menu.

2. Set the ODDMUSE_CHANGES environment variable to Updates. This makes sure that clicking on the link is the equivalent of visiting /changes.

3. Edit the changes.sp6 template and replace occurences of "Changes" with "Updates" in the title element and the h1 element such that there is no mismatch between the link and the title.

Resources

The following variables point to directories used to server resources.

• ODDMUSE_IMAGES
• ODDMUSE_CSS
• ODDMUSE_TEMPLATES
• ODDMUSE_WIKI

For images, css files and templates, this is how lookup works:

1. If an environment variable with the correct name exists, it's value is used as the directory. Since the .cro.yml file does that, you can simply run cro run and it should find all the files.

2. If no environment variable exists, the current working dir is checked for directories with the right names. If they exist, they are used. This is important when you run raku -I lib service.pm6 directly, since that ignores the .cro.yml file.

3. If none of the above, the copies in the resources folder of the module itself are used, if you installed Oddmuse via zef.

As for the wiki directory: it is created if it doesn't exist. At that point the Home.md page from the module's resources folder is copied so that your wiki comes with at least one page. As this refers to the resources folder, it only works if you installed Oddmuse via zef.

Images and CSS

Your website needs two directories for the static files:

• ODDMUSE_IMAGES is where logo.png is. This is used for the favicon.ico. Files from this directory are served as-is. You could use the logo image in your templates, for example.

• ODDMUSE_CSS is there default.css is. This is used by the default templates.

These directories can be shared between various instances of the wiki.

Templates

This is where the templates are. The templates use the Mustache format.

Wiki

This is where the dynamic content of your wiki is. If you use the Storage::File back end, it contains the following:

• page is where the current pages are saved
• keep is where older revisions of pages are kept
• rc.log is the log file

Example: Changing the CSS

Here's a simple change to make:

mkdir css
cp resources/css/default.css css/
cat - << EOF >> css/default.css
body {
  background: black;
  color: green;
}
EOF
ODDMUSE_HOST=localhost ODDMUSE_PORT=8000 raku -I lib service.p6

This works because now we're not using cro to launch the process and thus .cro.yml isn't being used and thus the environment defined in that file isn't being used. That's why we had to provide our own host and port, and that's why the modified default.css from the local css directory is being used.

Taking it from here should be easy: the templates directory and the images directory work just the same.

If you want these changes to take effect and you still want to cro run, you need to make changes to the .cro.yml file.

Spam Protection

There is currently a very simple protection scheme in place, using three pieces of information in three environment variables:

1. ODDMUSE_QUESTION is a question
2. ODDMUSE_ANSWER are possible answers, comma separated
3. ODDMUSE_SECRET is a secret which can be stored in a cookie, which basically means you should only use alphanumeric ASCII characters: no spaces, nothing fancy

This is how it works: whenever somebody tries to save a page, we check if they have answered the question. If they do, they'll have a cookie holding the secret. If they don't we redirect them to a page where they must answer the question. If they answer correctly, the cookie with the secret is set and the page is saved.

As the secret is stored in the cookie, people have to answer the question whenever they delete their cookies, or whenever they change browsers.

An example setup might use the following settings, for example:

ODDMUSE_QUESTION=Name a colour of the rainbow.
ODDMUSE_ANSWER=red, orange, yellow, green, blue, indigo, violet
ODDMUSE_SECRET=rainbow-unicorn

Hosting Multiple Wikis

Create two empty wiki data directories:

mkdir wiki1 wiki2

Start the first wiki:

ODDMUSE_HOST=localhost ODDMUSE_PORT=9000 ODDMUSE_WIKI=wiki1 raku -Ilib service.p6

Start the second wiki:

ODDMUSE_HOST=localhost ODDMUSE_PORT=9001 ODDMUSE_WIKI=wiki2 raku -Ilib service.p6

Now you can visit both http://localhost:9000/ and http://localhost:9001/ and you'll find two independent wikis.

Docker

I'm not sure how you would go about building the docker image. Any help is appreciated.

docker build -t edit .
docker run --rm -p 10000:10000 edit