introduction

This file serves the purpose of providing a quick reference to help you get set up with hosting org-based html exports on the internet, which greatly facilitates sharing your reproducible workflows with non-org-mode users.

It's still a WIP, any feedback is more than welcome at paul[at]lodder.dev.

what you need

a server

To host org-based exports on the internet, you need a server. In other words, you need a computer that is running all the time, and is able to serve your website to any user on the internet visiting your website.

In my early days of programming I never really knew what a server was exactly, until I understood that it is nothing more than a computer, much like your laptop or desktop computer. It can do the exact same things, but a server tends to be used more to refer to a computer at a remote location that is running all the time. You could host a website on your laptop, but every time you would close your laptop or lose connection to the internet, your website would be unavailable.

You can rent a server, and you want to look for a VPS (virtual private server), I rent mine at https://transip.com, but there's plenty of options available. When ordering the server, don't get confused by the additional web-hosting packages they might offer you; you don't need those to host a website.

a domain name

If you visit a website, e.g. lodder.dev, you are actually redirected to the IP address of the server under the hood. You can think of the IP address of a server as its unique identifier or address on the internet. This also means that you don't strictly need a domain name to serve content on the internet, you could just visit the IP address directly. But https://lodder.dev, looks better than 149.210.193.148.

So you'd need to buy, or more like rent, a domain name. Now what does it mean to have a domain name? It means that you have control over the IP address that this domain name will be associated with. Once configured, the DNS servers, which take care of this domain name-IP address link, will have a record of your domain name and the corresponding IP address of your server.

To configure this for your domain name, go into the DNS settings and add a record that tells it to associate your domain name to the IP address of your server. As an example, these are two records from my DNS settings:

Hostname Type TTL Data
lodder.dev A 1 hour 149.210.193.148
3d.lodder.dev A 1 hour 149.210.193.148

These records instruct the DNS servers to make sure that anyone visiting lodder.dev or 3d.lodder.dev is redirected to the server residing at 149.210.193.148. However as you can see, these are two different pages, yet they are redirected to the same IP address, so how does that work?

a web server framework

Upon visiting any of these above two websites, your browser (the requester) is knocking on the door of my server and requesting 3d.lodder.dev or lodder.dev. But my server needs to know how to respond to either of those websites; it needs to look up the different files and send them to the requester.

A framework facilitating this server <--> requester interaction is called a web server. Common examples are Apache and NGINX (which I use). The following NGINX configuration tells my server to respond to a request to http://lodder.dev by serving/returning the file /home/paul/org-homepage/index.html.

server {
    listen 80;

    server_name lodder.dev;

    location / {
        index index.html;
        alias /home/paul/org-homepage/;
    }
}

The alias part takes care of any nested directory and folder structures, so that if you visit lodder.dev/blog/hosting-an-org-based-website.html, it returns the file /home/paul/org-homepage/blog/hosting-an-org-based-website.html.

!Note! this means that any file under /home/paul/org-homepage will be accessible by its relative path on lodder.dev, so /home/paul/org-homepage/some-secret can be accessed by lodder.dev/some-secret.

short recap

So: upon visiting lodder.dev, the DNS servers are asked "what's the IP address of lodder.dev?", allowing your browser to connect to your server. My server then uses a web server framework (NGINX) to host the right content in response to your request.

TODO https vs. http

Now to configure https, you can use certbot to have your website be accessible over https, instead of http. More on this later.

Date: November 24, 2022