PagePark

I wrote this simple HTTP server to park domains I've bought but not yet used.

Then I kept going and added all the features I want to help me manage my own websites, far beyond just parking them. I liked the name so I kept it. Think of it as a nice park where you keep your pages. ;-)

It's written in JavaScript and runs in Node.js.

Each domain is in its own folder. The content for that domain is in the folder. It can serve Markdown docs, or optionally run JavaScript code. And of course HTML, text files, images, movies, etc.

Yet it's still very simple. Which is the point. ;-)

It's 90 percent of what all web servers do, so if you learn how to run PagePark, you're learning how to run a web server. A real one you can use to host your sites. And it's easy to hack the code if you want to.

How to

How to get started quickly with PagePark.

0. Install Node.js if you don't already have it running, including the NPM package manager.

1. Download the PagePark folder <a href="https://github.com/scripting/pagepark/archive/master.zip">from</a> the GitHub repository.

2. At the command line enter <code>npm install</code>.

3. To run the server, enter <code>node pagepark.js</code>.

4. Create a sub-folder of the domains folder called localhost.

5. Using a text editor add a file to the localhost folder called index.md. Put whatever you like in the file. Save it.

6. In a browser, running on the same machine, enter localhost:1339. You should see the text you entered in the previous step.

If this worked, congratulations -- you just installed a web server. :-)

Screen shot

Here's a <a href="http://scripting.com/2015/01/04/pageParkFolderScreenShot.png">screen shot</a> of an example PagePark <i>domains</i> folder.

How it works

1. PagePark will automatically create a prefs sub-folder and a domains sub-folder.

2. Add your web content under domains. Each folder's name is the name of a domain. The contents within the folder are what we serve. <a href="http://scripting.com/2015/01/04/pageParkFolderScreenShot.png">Screen shot</a>.

3. Serves all major media types including audio and video. Files whose names end with .md are passed through the built-in Markdown processor. Files ending with .js are interpreted as scripts only if the associated <a href="docs/config.md">config</a> setting is turned on. The text they return is what we serve. Here's an <a href="https://gist.github.com/scripting/2b5e237a105b6cb96287">example</a> of a script that I have <a href="http://lucky.wtf/badass/butt.js">running</a> on one of my servers.

4. The prefs folder contains a file of settings you can change, prefs.json. These include the port that the server runs on and the name of the index file (see below).

5. stats.json contains information generated by the server including the number of times the server has started, how many hits it's received (all time and today), and hits by domain.

6. mdTemplate.txt is the template we use to serve Markdown text. You can edit this file to provide a common template for all your Markdown documents.

7. If a request comes in for a folder, we scan the folder for a file whose name begins with index and serve the first one we find. So the index file can be HTML, Markdown or a script, or any other type PagePark can serve.

8. If you want to run PagePark from a folder different from the one that contains the app, set the pageparkFolderPath environment variable to point to that folder.

9. There are three special endpoints on all domains: /version, /now and /status that return the version of PagePark that's running, the time on the server and the stats and prefs.

File extensions

The extension of a file determines how PagePark serves it.

<table> <tr> <td>

.txt

</td> <td>

The text in the file is returned, the type is text/plain.

</td> </tr> <tr> <td>

.xml

</td> <td>

The text in the file is returned, the type is text/xml.

</td> <td>

<a href="http://lucky.wtf/davetwitterfeed.xml">davetwitterfeed.xml</a>

</td> </tr> <tr> <td>

.json

</td> <td>

The text in the file is returned, the type is application/json.

</td> <td>

<a href="http://lucky.wtf/wodemo.json">wodemo.json</a>

</td> </tr> <tr> <td>

.png

</td> <td>

The contents of the file is returned with type image/png.

</td> <td>

<a href="http://lucky.wtf/tree.png">tree.png</a>

</td> </tr> <tr> <td>

.opml

</td> <td>

The outline is rendered as an expandable outline, the type returned is text/html.

</td> <td>

<a href="http://lucky.wtf/states.opml">states.opml</a>

</td> </tr> <tr> <td>

.md

</td> <td>

The text in the file is passed through a Markdown processor and that text is returned. The type returned is text/html.

</td> <td>

<a href="http://lucky.wtf/test.md">test.md</a>

</td> </tr> <tr> <td>

.js

</td> <td>

We run the script, and the return value is returned to the caller, with type of text/html. Here's the <a href="https://gist.github.com/scripting/fd9e6720834958130f0a3d53b9f8dd15">source code</a> for the script in the demo below.

</td> <td>

<a href="http://lucky.wtf/badass/butt.js">butt.js</a>

</td> </tr> </table>

Port 1339

The first time you run PagePark it will open on port 1339. You can change this by editing prefs.json in the prefs folder.

This means if you want to access a page on your site, the URL will be of the form:

http://myserver.com:1339/somepage.html

The normal port for HTTP is 80. That would have been the natural default, however a lot of Unix servers require the app to be running in supervisor mode in order for it to open on port 80. You can do this by launching PagePark this way:

sudo node pagepark.js

I made the default 1339 because I wanted it to work "out of the box" for first-time users.

Mapping port 80 to 1339

Here's a magic incantation that works on Ubuntu that maps requests for port 80 to port 1339.

<pre>sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 1339 sudo iptables -t nat -A OUTPUT -p tcp -o lo --dport 80 -j REDIRECT --to-ports 1339</pre>

If you have questions about how and why this is necessary, see <a href="https://github.com/scripting/pagePark/issues/17">this thread</a> on the PagePark repo.

Example pages

http://morningcoffeenotes.com/ -- simple home page

http://lucky.wtf/ -- images

http://lucky.wtf/test.md -- markdown page

http://lucky.wtf/badass/ -- index file in a sub-directory

http://lucky.wtf/nosuchfile.html -- file not found

http://lucky.wtf/version -- the version of PagePark that's running on the server

http://lucky.wtf/now -- the time on the server

http://lucky.wtf/transcend.opml -- a page written in OPML

http://lucky.wtf/transcend.opml?format=opml -- the OPML source of the page

config.json files in domains folders

On every request, PagePark looks at the top level of the domain folder for a file named config.json. If it finds it, it reads it and the values in the file control how the request is handled.

Here's a <a href="https://github.com/scripting/pagePark/blob/master/docs/config.md">docs page</a> that lists the values and what they control.

JavaScript sample code

I've iterated over the code to try to make it good sample code for JavaScript projects.

I wanted to make code that could be used for people who are just getting started with Node, to help make the process easier.

There will always be more work to do here. ;-)

Updates

v0.8.27 9/22/22 by DW

There's a new version of the marked package that breaks pagepark.

Changed <a href="https://github.com/scripting/pagePark/blob/master/package.json#L24">package.json</a> to use the last version that worked.

v0.8.26 11/12/21 by DW

Added new call for apps running on the same machine as PagePark that makes it possible to find out if a particular domain his being served by PP.

The feature was <a href="https://github.com/scripting/pagePark/issues/25">discussed</a> in this RFC thread.

v0.8.25 8/25/21 by DW

<a href="https://github.com/scripting/pagePark/blob/master/docs/config.md#urlglossary-for-individual-websites">urlGlossary in config.json</a>.

v0.8.24 8/20/21 by DW

<a href="https://github.com/scripting/pagePark/blob/master/docs/config.md#templates-for-individual-websites">Templates for individual websites</a>.

v0.8.23 7/28/21 by DW

<a href="https://github.com/scripting/pagePark/blob/master/docs/config.md#serving-configjson">config.flServeConfigJson</a> -- a new config value -- defaults false. Possible breakage.

Updated the <a href="https://github.com/scripting/pagePark/blob/master/docs/persistentapps.md">persistent apps docs</a>. It previously said there was no way to launch a new app once PagePark has booted. This is no longer true, there is a command-line command that does a rescan of the folders, and launches any newly qualified apps.

Updated the <a href="https://github.com/scripting/pagePark/blob/master/cli/readme.md">command line tool docs</a>. A few commands were added since the docs were written.

v0.8.22 7/25/21 by DW

We allow you to specify config.defaultExtension with a leading dot, for example ".opml" or ".md".

It's a common thing to do so why not make sense of it?

v0.8.21 7/25/21 by DW

New <a href="https://github.com/scripting/pagePark/blob/master/docs/config.md#defaultextension">defaultExtension</a> value in config.json.

v0.8.20 7/5/21 by DW

If a request comes in for a host that doesn't have a corresponding domains folder, and there is a folder called default, we serve the request from the default folder.

A <a href="https://github.com/scripting/pagePark#v057-51115-by-dw">wildcard folder</a>, if it exists, takes precedence, for examle if a request comes in for yo.bullmancuso.com, and there is no domains folder with that name, and there is a wildcard folder, *.bullmancuso.com and a default folder, the request goes to the wildcard folder.

You can put a config.json file in the default folder.

v0.8.18 6/22/21 by