Org Website Backend

• Org Website Backend
  • Introduction
  • What this backend does
  • Why Dart?
  • Why SCSS?
  • How to run this backend
    • Running locally
    • Docker
    • Docker-compose
  • Running in development mode
  • How can I use this in my org files?

Org Website Backend

Introduction

Org Website Backend, or OWB, is a backend I created for my org-generated static websites. It was originally developed as a backend for my linguistics website langue.phundrak.com, but eventually I began using its Dart and Scss source code with other generated websites and pages of mine, such as my configuration website hosted on phundrak.com/config. I now want to just have it stand on its own, while my org-generated websites stay Dart and Scss code free.

What this backend does

This has one goal: provide my org-generated websites a beautiful and unified interface. This is achieved by reorganizing the HTML generated by Emacs when publishing my org files, and by reading dynamically the website’s sitemap in order to generate some user menus so they can navigate freely on the website without the need to go back to the main page.

Visually, it also provides the user three themes:

• a light theme, enabled by default
• a dark theme, easier on the eyes
• a black theme, easier on smartphones’ battery if they have an AMOLED screen

The user’s preferences are kept on their browser’s local storage, so no cookies are used.

Why Dart?

Dart is a programming language developed by Google, which aims to be compilable as native code or as Javascript code. In this case, I use it compiled as Javascript. Why not Javascript then? I personally find Dart much easier to work with, and to be a way saner language than Javascript is. It also ensures type-safety and —to some extent— some compile-time code verification. The dart compiler also performs some optimization at compile-time, which is really benificial.

Why SCSS?

SCSS is a superset of CSS which aims at simplifying CSS users’ life, and it’s really good at its job. I especially enjoy being able to nest blocks within one another, there’s no more need to rewrite endlessly some lines that could simply be generated by SCSS. Why SCSS and not SASS? The answer is simple: I have a buggy SASS installation, but SCSS works fine. Yep, simple as that.

Another thing is that I use the Ruby implementation of SASS. The reason for that is also simple: it is the only one that provides a --watch option so it automatically recompiles SCSS code to CSS when the SCSS code is changed.

How to run this backend

This backend delivers only two main files:

• /dart/main.dart.js The main dart file compiled to Javascript (you don’t need to worry about the others),
• /style/style.css The main style file compiled to CSS.

This is everything you need for beautiful org-generated websites.

Running locally

You could install Dart on your machine, as well as the Ruby implementation of SASS with its dependencies. Next, you will need to install webdev and install the Dart dependencies:

  $ pub global activate webdev
  $ pub get

By the way, you have to ensure your Dart cache’s bins are in your $PATH. They are generally installed in your $HOME/.pub-cache/bin directory.

Then, you have to run start.sh, and you’re good to go! Content will be delivered on the 8080 port. If you wish to deliver content to another port, you can edit this file.

  ./start.sh

Docker

A Dockerfile is also provided so you can run this server inside a Docker container, and thus you can avoid the hassle of installing Dart and Ruby Sass. In order to run OWB, you can first build the Docker image:

  docker build . --tag owb:1.0

And then you can run it:

  docker run \
    -p 8080:8080 \
    -v ./web:/app/web \
    --restart always \
    --detach \
    --name owb \
    owb:1.0

Docker-compose

This repository also provides a docker-compose.yml file for easier Docker usage with docker-compose. If you wish to run your backend in release-mode, simply run the following:

  docker-compose up --detach

Running in development mode

To run this backend in development mode, you can add to your environment the variable RELEASE with the value debug. Running the backend locally, you would start it like so:

  RELEASE=debug ./start.sh

Running it with Docker, you would use the following command:

  docker run \
    -p 8080:8080 \
    -v ./web:/app/web \
    -e RELEASE=debug \
    --restart always \
    --detach \
    --name owb \
    owb:1.0

And with docker-compose, you would add the following line to your owb service:

  environment:
    - RELEASE=debug

Any other value to this environment variable will make your backend run in release mode (actually, it will only make webdev run in release mode).

How can I use this in my org files?

Let’s say you serve your files on org.example.com, add the following lines to the top of your org file:

  #+HTML_HEAD_EXTRA: <link rel="stylesheet" href="https://org.example.com/style/style.css"/>
  #+HTML_HEAD_EXTRA: <script defer src="https://org.example.com/dart/main.dart.js"></script>
  #+HTML_HEAD_EXTRA: <script src="https://kit.fontawesome.com/yourtokenhere.js" crossorigin="anonymous"></script>

You will need to obtain a (free) license on Fontawesome to use fontawesome’s icons. Then, once you have this license, use your token provided by them to edit the third header above.

Another option is to redirect any request of your website directed to /dart or /style to your running instance with the help of your reverse proxy, such as Nginx. You could have for example the following lines:

  location /dart {
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_pass http://localhost:8080/dart;
  }
  location /style {
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_pass http://localhost:8080/style;
  }
  location /packages {
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_pass http://localhost:8080/packages;
  }

Of course, be careful to write the same port in the rules above as the port your backend is serving on.