Fargo Publisher is a node.js app that connects to Fargo to publish a folder of HTML docs.
Fargo 2, released in February 2014, has a new built-in content management system that creates static HTML files. All that's needed is a way to flow those files to a static HTTP server. That's what Fargo Publisher does.
It defines an open protocol that any app can use to connect to static storage, no matter where the content originates. This implementation stores the files in Amazon S3, but a fork of this project could store them in files, or in another content server.
It's open source, using the MIT License.
This document includes information you need to install a server, and technical information for implementers.
Each outline can be given a public name.
Rather than invent our own naming system, we're using the Internet's -- DNS.
So if I call my outline "dave" -- you can refer to it as dave.smallpict.com.
When you go to that address, you get the rendered content.
There's only one element of the <head> section of that outline that we care about, <linkHosting>. It's automatically maintained by Fargo.
The rest of the outline contents is up to the user.
The Fargo user brings the outline he or she wants to make public to the front.
Choose the Name Outline command in the File menu.
A dialog appears.
Type a name. As you type the software tells you whether the name is taken. It does this with a call to Fargo Publisher.
When you click OK, a message is sent to Fargo Publisher to associate that name with the public URL of the outline. Getting a public URL for a file is a feature of Dropbox.
When the user publishes an outline, or a portion of an outline, it could cause many files to be rendered.
The text of those files is saved to a package file, which is linked into the user's outline, automatically by the CMS.
When the text is fully rendered, it sends a message to the Publisher server with the name of the outline.
Publisher then reads the outline (it was registered in the previous step) locates the package file, reads it, breaks the package up into its component files and saves them to the user's folder in the S3 bucket.
Publisher sends back to Fargo the base URL of the folder, which is then hooked into the Eye icon, which can be used to view the headline the cursor points to.
The Eye icon in the left margin of Fargo is super-important.
It connects the editing context with the viewing context.
Put the cursor on any headline in a public outline, and click the Eye.
A new tab opens with the rendered view of that section of the outline.
You're going to need to make a few decisions before you deploy.
-
The user files will be stored in an S3 bucket. There is an S3 path for that location. What should it be?
-
Where do you want to store the FP data? This includes information about the user's outlines, and stats generated by Fargo Publisher. It's also an S3 path. You might not want this to be public, although there is no personal information stored about the user outlines. It's all designed for publishing. These are public outlines, by definition.
-
What domain for the user names? You have to own the domain and the DNS should point to the node server so it can redirect to the user's content when subdomains are accessed.
-
What port do you want the server to run on? If you don't specify it, the server will boot on port 80.
-
Do you want Fargo Publisher to redirect to the content or serve it directly? (The default is to redirect.)
For my deployment I went with (Unix shell commands):
-
export fpHostingPath=/beta.fargo.io/users/
-
export fpDataPath=/beta.fargo.io/data/
-
export fpDomain=smallpict.com
-
export fpServerPort=80
-
export fpRedirect=false
You must have a current node.js installation.
Install request, AWS and if necessary url.
Set environment variables for AWS.
-
AWS_ACCESS_KEY_ID
-
AWS_SECRET_ACCESS_KEY
Set environment variables with your S3 paths and the domain you're using.
-
fpHostingPath -- where the users' files will be stored.
-
fpDataPath -- where you want names and stats to be stored.
-
fpDomain -- the domain we're allocating.
The app is in package.js. package.json already contains all the info that node needs to run it.
It's been over a year since the last update to Fargo Publisher, and I've learned a lot about Node and JavaScript since then.
The major change in this release is that you can now specify all the environment variables in a file called config.json in the same folder as the publisher.js file. The values in this file take precedence over the environment variables. You still have to set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY through environment variables because that's where the AWS software will look for them.
I'm no longer maintaining the OPML versions of the files, so I removed the folder from the repository.
Same with worknotes.md.
I was previously running my server on Heroku, but now am running it along with my other server software on a Ubuntu instance on AWS.
There's a folder of OPML files in the repository that contains the outlines that the JavaScript and Markdown come from.
We use the MIT License. Nothing proprietary about the protocol or the code. You are encouraged to clone, innovate, enjoy.
I love programming in this mode. The tools are great, and node is a wonderful environment, made that way by programmers who share their work so generously. The quality of the work is very impressive. And the commitment to no breakage also refreshing in this day and age.
Thanks to Brent Simmons for his Hello World server example. It helped this node newbie get started. He says his example is for Cocoa developers, but that's not true. I understood it, and I've never written a line of Cocoa in my life, and think it's a silly name for a programming environment. ;-)