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.