Freesite HOWTO

This is a guide to making websites for use on Freenet, known as freesites. The process is similar to making standard websites, but there are few things that work differently due to things like the latency and storage model of Freenet. I also give some tips on how to ensure that your freesite is accessible as fast as possible to the highest number of readers, and how to publicise it effectively. I will assume you have a basic knowledge of HTML.

The basic idea is that you design your webpage as usual using HTML and CSS and then you upload the files to Freenet using an SSK key.

FProxy

FProxy is the magic that allows you to use a standard web browser to view freesites.

The Freenet node allows you to store files in the network, and retrieve files from the network, including HTML files, but it doesn't natively speak the HyperText Transfer Protocol (HTTP) used by web browsers to retrieve webpages from webservers. FProxy, which is short for the Freenet Web Proxy, is a proxy web server that sits between your web browser and the Freenet node, and translates HTTP requests from the browser into file requests that the Freenet node can understand.

FProxy is part of the main Freenet program, and is enabled by default. It listens on the local interface on port 8888. (Normal websites use port 80.) To use it, you just take any web browser and go to the address http://localhost:8888/ . If your computer doesn't understand the name localhost, replace it with the equivalent IP address 127.0.0.1 like this: http://127.0.0.1:8888/

If you have the computer that runs the Freenet node on a local network, you can use FProxy from a different computer like this: http://mynode:8888/, where mynode is the name or IP address of the computer running the Freenet node. You will need to change the IP address to bind to parameter on the FProxy config page first.

Freenet provides some default pages in FProxy for administering your node: viewing the file transfer queue, your peers, statistics, etc.

If someone gives you a USK key of a freesite, you simply append it to the end of the basic FProxy URL in order to view the freesite, like this: http://localhost:8888/USK@yGvI...U79s,AQACAAE/toad/10/

If you use a USK key, like the one above, Freenet will automatically look for the latest version of the site. If you use the similar SSK key, Freenet will fetch only the edition you specifically ask for.

Freesite addresses

Regular websites have a user-friendly name like www.google.com, where the name is registered with a centralised authority. Freenet is decentralized, so that approach doesn't work. Instead, the addresses of freesites are determined based on their content, or on a secret key held by the freesite owner. Unfortunately this means that freesite addresses are long strings containing about 100 random-looking characters, so they aren't easy to memorise. But if you are just linking to them using a HTML anchor tag like <a href="/USK@d5K..../myfreesite/4/">, that isn't a problem.

Freesite addresses are also knowns as keys, because they locate and decrypt the files that they point to. Freenet has two basic kinds of keys: Content Hash Keys (CHKs) and Signed Subspace Keys (SSKs). These keys are strings of about 100 random-looking characters. One part of the key identifies where in the network the (encrypted) file is most likely to be stored, and another part of the key decrypts the file once it is retrieved.

Content Hash Keys (CHKs)

Content Hash Keys are totally dependent on the file they locate: if two people separately insert the same file to Freenet, they will both get the same CHK as a key for retrieving that file. CHKs look like this:

CHK@b7j....../myfreesite.html

You probably don't want to use a CHK as a key to your freesite, because if you change the site at all and reinsert it, you will get a totally different key.

Signed Subspace Keys (SSKs)

Signed Subspace Keys are a way of signing the key using a secret that only you know, so that people can be assured the file was inserted by you. So you can insert two different files to Freenet and people will know by looking at their SSKs that they were both inserted by the same person.

To insert a file to Freenet identified by an Signed Subspace Key, you first need an SSK keypair. This consists of two SSK keys, one of which is secret and only used by you to insert files. The other is the public SSK string that other people will use to access your file. We will see a program called jSite later on that generates this pair of keys for you.

This is particularly useful for freesites, since you are almost certainly going to need to update your freesite. When you insert the second edition of your freesite, people will need to know that you are the same person that inserted the first edition. So your first edition could be like this:

SSK@d5K....../myfirstfreesite.html

and your second one could be signed with the same key and look like this:

SSK@d5K....../mysecondfreesite.html

The problem with this idea is that it makes it difficult to automate the process of looking for newer versions of your freesite. So instead, the convention is to use a number in a well defined place to indicate the version:

SSK@d5K....../myfreesite-1/index.html
SSK@d5K....../myfreesite-2/index.html
SSK@d5K....../myfreesite-3/index.html

Now someone looking at a version of your freesite can keep incrementing the version number to see if there is a newer version. But it would be nice to have our Freenet node do this automatically for us. After all, computers are supposed to make our lives easier, right? So the next step is to use Updateable Subspace Keys (USKs).

Updateable Subspace Keys (USKs)

Updateable Subspace Keys are almost identical to SSKs - they point to exactly the same data. The difference is that when you request a file using a USK, it triggers a process in your Freenet node to look for the most recent version. The format of the number is changed slightly as well. So if someone requests the fourth edition of your site using this key:

USK@d5K....../myfreesite/4/index.html

and you have already inserted the fifth and sixth versions, then their node should automatically send the content of this key to their browser, instead of the one they requested:

USK@d5K....../myfreesite/6/index.html

You will need to insert your freesite using a secret SSK key, and then advertise and link to your freesite using the USK version of that key. That way, people should always be taken to the most recent version of your site, even if there are still links on other people's pages to older versions.

Designing Your Freesite

You can design your website using whatever tools you prefer: text editor, Dreamweaver, Bluefish. Store all the files in a directory. You can use subdirectories as well, if you like. You can use images and favicons.

You can use HTML and CSS, but anything that could cause a freesite to connect to something external to Freenet will get filtered out by Fproxy, because it could be used to identify your IP address and thus destroy your anonymity. This includes Javascript, links to standard websites, images or CSS files hosted on standard websites and embedded objects such as Flash. So avoid using anything like this.

Keep It Simple

Freenet has a high latency, meaning it can take a while for sites to download, especially if you are used to broadband speeds. This is the necessary price you pay for anonymity.

As a consequence, you should try to keep the size of your freesite to a minimum, and don't require too many clicks to navigate around your site. This means:

Remember that Freenet stores data in chunks of 32kB. So roughly speaking, every extra 32kB of data you add to your freesite can add several seconds on to the retrieval time.

When you insert a lot of files to Freenet together under one SSK key, your node will automatically package files together before compressing them, to save space. These packages are called containers and hold roughly 4MB of files. You have no direct control over which files are grouped together, so you really need to keep your freesites less than this size. Even this size site could take a while to download, so even smaller is better.

Images

Remember that the root of your freesite as far as FProxy is concerned is the part before the USK. So to include images within your own freesite, use syntax like this (note no slash at the start):

<img src="mypic.jpg" alt="description of mypic"/>
<img src="images/mypic.jpg" alt="description of mypic"/>
<img src="../mypic.jpg" alt="description of mypic"/>

For the last example, note that you would need to be in a HTML file that is in a subdirectory. Be sure to use alt attributes on your img tags since people are more likely to be browsing with images turned off for speed, or to have problems retrieving images.

You can include images that are stored on other freesites - in fact this is positively encouraged - see the Activelink section. Use a syntax like this (note the slash at the start):

<img src="/USK@d5K..../othersite/5/otherimage.jpg" alt="description of image"/>

It is a very good idea to add an alt attribute to all your images, because some people may browse with images disabled or using a text browser, or the images may take a while to come through, or they may be blind and using a screen reader.

Activelink Images

Activelink images are very important for ensuring that a freesite will be fetchable in a reasonable time, so make sure your site has one. An activelink is just an image in your site that can be used by another site to link to yours. On a regular website this kind of behaviour is called "leeching" and it frowned upon. But on Freenet it is very beneficial.

The great advantage of this to you is that if another site includes your image in their site, then anyone visiting their site will also be pulling a large part of your site into their Freenet cache. This is because of the containers that Freenet uses to group together files that are part of the same insert.

By convention, an activelink is stored in the root directory of your site, is called activelink.png and is 108 pixels wide by 36 pixels high. It is best to stick with this convention as otherwise it makes it difficult for other people and for Freenet spiders to identify your activelink. Here is the activelink for this freesite:

Freesite HOWTO activelink

This is the code you would need to include in your HTML to link to this site using an activelink:

<a href="/USK@8r-uSRcJPkAr-3v3YJR16OCx~lyV2XOKsiG4MOQQBMM,P42IgNemestUdaI7T6z3Og6P-Hi7g9U~e37R3kWGVj8,AQACAAE/freesite-HOWTO/1/">
<img src="/USK@8r-uSRcJPkAr-3v3YJR16OCx~lyV2XOKsiG4MOQQBMM,P42IgNemestUdaI7T6z3Og6P-Hi7g9U~e37R3kWGVj8,AQACAAE/freesite-HOWTO/1/activelink.png" alt="Freesite HOWTO" width="108px" height="36px"/>
</a>

A freesite without an activelink is much more likely to die out over time than one without, unless it is very popular.

If your freesite is getting large, consider splitting it up into separate sites (you can still use the same key for them all, just change the site name) and have activelinks connecting them.

Favicons

A favicon isn't essential, but it is a nice touch. Favicons are the little images that web browsers display in the Favourites list, or next to the address bar, or on the browser tabs. For example, Google's favicon is a blue letter G in a white box with a multicolored border: Google's favicon.

Create a special .ico file called favicon.ico using your favourite image program like the GIMP or Photoshop. 16x16 pixels should be fine. Put it in with your freesite files and let the browsers know it is there using code like this in the head section of your page:

<link rel="shortcut icon" href="images/favicon.ico" />

Links

Although freesites can't link to external websites, to protect your anonymity, they can obviously link to other freesites. Use syntax like this:

<a href="/USK@d5K..../othersite/5/otherpage.html">mylink</a>

Note that the slash at the start is very important, otherwise it will think you are referring to a file within your own website called USK@d5K..../othersite/5/otherimage.html

To link to other pages in your own freesite, there is no need to include the USK part:

<a href="myotherpage.html">
<a href="subsection/myotherpage.html">
<a href="../myotherpage.html">

CSS

CSS stand for Cascading Style Sheets. They are a useful way to separate the logical markup used by HTML (paragraphs, headings, etc.) from the style markup (colors, fonts, sizes, etc.).

If your site has several pages, sharing the CSS style information in a separate file is a good idea to cut down on the overall size of the site, as well as for ease of updating. So put your style information in a file called something like styles/main.css and use this in the HTML head section:

<link rel="stylesheet" href="styles/main.css" type="text/css"/>

But if your site has only one file, the problem may be that the browser downloads the HTML before it finds the CSS file. So in this case, you might want to include the CSS in style tags in the header of the HTML file like this:

<style type="text/css">
h1 { color:#FF00000; }
p { font-size:small; }
</style>

Title Tag

Every freesite should have a title in the head section of the HTML. Spiders will use this to display a meaningful title for your freesite. It should look something like this:

<title>This is the Title of My Freesite</title>

Description Meta Tags

There are several automated spiders that crawl Freesite links and generate indexes of freesites. They use things like descriptions in meta tags to store brief descriptions about the site. So add a line like this to the head section of your freesite:

<meta name="description" content="This is a brief description of my freesite."/>

Language Meta Tag

Freesites can come in many different languages. It is a good idea to let browsers and spiders know what language your site is written in. You can do this by adding a language meta tag in the head section of your page like this:

<meta http-equiv="Content-Language" content="en"/>

If your site uses XHTML you can also add it to the html tag like this:

<html xml:lang="en-US" xmlns="http://www.w3.org/1999/xhtml" lang="en-US">

Character Set Meta Tag

Closely connected to the webpage's language is its character set. This is the set of letters that are associated with each raw numerical byte of the page. FProxy will serve up freesites with a Unicode character set of UTF-8 by default, and this is a good choice to stick with, since it covers virtually all languages, and Freenet uses UTF-8 internally.

You can also specify the character set inside the HTML file itself, if you use a different character set for some reason, or in case someone isn't using FProxy to view the site. It is a good idea to do this, since browsers are always accurate at guessing the intended character set. Use code like this:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

If you use a single-byte character set like ISO-8859-1 instead of UTF-8, then any non-standard characters in your site are likely to display improperly in the user's browser.

Category Meta Tags

Some index sites, such as The Ultimate Freenet Index will use a meta tag to classify your site into categories. Use code like this in the head part of your site:

<meta name="category" content="flog,games,movies"/>

Add To Bookmarks Link

You can provide a clickable link on your site so that people can easily add a bookmark to your site from their FProxy homepage at http://localhost:8888/. This means they will be notified whenever you update your freesite. If you have an activelink, they can use this in their bookmarks list too, which means they will be fetching and caching your freesite whenever they visit their FProxy home page.

To create the "add bookmark" link, use code like this on your site:

<a href="/?newbookmark=USK@...AAE/myfreesite/4/&amp;desc=My Freesite">bookmark my site</a>

Validating Your Freesite

You may want to check your pages are using correct HTML by using an offline HTML validator such as the one here: http://htmlhelp.com/tools/validator/offline/index.html.en

Uploading Your Freesite

Now all the hard work has been done, it is time to upload your freesite into Freenet.

You can use any Freenet file upload utility to do this, but jSite is recommended because it is designed especially for uploading freesites.

jSite

jSite is a Java application that simplifies the process of uploading a freesite to Freenet. It comes bundled with Freenet in a subdirectory called jSite. You run it by double-clicking on the jSite.jar file (in Windows or Mac) or by running this from the command line (in Linux):

$ java -jar jSite.jar &

Click on the Add Project button and it will create a new project for you and generate a pair of SSK keys. The Request URI is part of the public address of the site. The Insert URI is the secret key that enables only you to update the site.

The main jSite screen, showing the generated key pair

Now give the project a sensible name and description. These are just for your use and aren't publicly visible. The Local Path field is the local directory where your freesite is stored. The Path field is the public name of your site that will appear after the SSK part and before the edition number.

So the key of your final project will be like USK@...iroho7Kg~RvM~s,AQACAAE/my-test-project/0/

The main jSite screen, showing the details filled in

Now click the Next button. The next screen allows you to set a default file for your freesite that gets shown if you don't append a HTML filename to the key. You can also set MIME types and choose certain files to use externally generated keys. The Container and Replacements don't work at the moment, so just ignore them. All we want to do is select the index.html file and check the Default file box.

The jSite Project Files screen, where you set the default file.

Then click the Insert now button to insert the freesite to Freenet:

The jSite Project Insert screen, which shows the insert progress.

It will take a few minutes, depending on how big your site it. Either click on the Copy URI to Clipboard button here to get your freesite key, or click next to return to the main jSite screen where you can also copy the freesite key for any of your freesites.

Advertising Your Freesite

If you have existing freesites, and you don't mind people knowing you are the author of both, add an activelink to your new site and the indexing spiders should pick it up.

Also, you can announce your freesite on the sites board on a Freenet forum such as Frost or the Freenet Message System. The index spiders prefer the announcement to be in a particular format like this:

Name: MySite
Location: USK@...RvM~s,AQACAAE/my-test-project/0/
Activelink: USK@...RvM~s,AQACAAE/my-test-project/0/activelink.png
Description: This is my test freesite.
Categories: freenet,testing

Good Luck, and get uploading those freesites!