QuickStart Guide

Here we go ...

---

1. Download pagekite.py

You can download the program here.

If you are more interested in tinkering with the source code or trying experimental versions, check out our Open Source wiki pages.

Note: pagekite.py version is currently optimized for web developers, and as such it is meant to be used from the command-line (cmd.exe in Windows, or Terminal on the Mac).

2. Run pagekite.py for the first time

The following command will walk you through the process of creating your first kite:

$ pagekite.py --signup

(On Windows, the first time you double-click on the pagekite.py icon, it will start the sign-up process automatically.)

Alternately, fly localhost:80 on a name of your choice like so:

$ pagekite.py 80 yourname.pagekite.me

If pagekite.py detects that you haven't signed up yet or are trying to use a new kite name, it will trigger the sign-up process automatically.

This may be enough to get you started. For more tips and tricks, read on!

3: Using pagekite.py

Basic concepts

• Kites: A kite connects one or more services on your computer to a publicly visible DNS name or URL. In the examples below, we use the name foo.pagekite.me.
• Services: A service can be a file or folder, a local web server, or any other local TCP server (such as SSH) which you might want to expose to the wider Internet.
• pagekite.py: The program used to create, maintain and manage kites and their services.

Flying kites - Apache, nginx, ...

Assuming you have a web server (for example Apache or Nginx) running on port 80 on your local machine, the following command will make it publicly visible:

$ pagekite.py 80 foo.pagekite.me

This will connect your localhost:80 web server to the publicly visible http://foo.pagekite.me/. More importantly, it will also allow you to use SSL/TLS encryption on https://foo.pagekite.me/. We recommend using the encrypted versions whenever possible!

You can replace 80 with other port numbers (3000 and 8000 are common values for web development).

Flying kites without a webserver

If you don't have a web server already installed, but just want to quickly expose a folder full of files or images, you can do so using pagekite.py's built-in web server:

$ pagekite.py /path/to/folder foo.pagekite.me

That will make the contents of that folder visible at: https://foo.pagekite.me/

Note that for security reasons, if the folder doesn't contain an index.html file then people will see an error when they visit the site. If you want to present them with a list of files instead, you can do this:

$ pagekite.py /path/to/folder foo.pagekite.me +indexes

Some basic security controls

Access controls can be enabled for a particular service, by using the +ip and +password flags, like so:

$ pagekite.py 80 foo.pagekite.me +ip/1.2.3.4=ok +ip/4.5.6=ok
$ pagekite.py 80 foo.pagekite.me +password/bjarni=testing

As illustrated in the IP example above, you grant access to multiple IP addresses (or /24 subnets), or multiple username/password pairs simply by adding multiple flags. When access controls are in use, unauthorized connections will be rejected.

If you just run pagekite.py with no arguments (or double-click on the program icon on your Desktop or in a file manager), it will fly all enabled kites and services present in your configuration file. See the management section below for details on how to manage these settings.

Naming your kites

When you sign up for service, you will be asked to choose a name for your default kite. You are not restricted to using just this name though:

1. You can create unlimited sub-kites: sub.foo.pagekite.me or sub-foo.pagekite.me
2. You can create a few new kites: foo2.pagekite.me
3. You can use unlimited CNAMEs from your own domain instead.

To create a CNAME kite, read this HowTo. To create a new .pagekite.me name, just use it! pagekite.py will detect that it is new and will walk you through the process of registering it.

$ pagekite.py 80 sub-foo.pagekite.me

Note: Due to browser limitations, automatic SSL encryption support is only available for names ending in pagekite.me that contain no extra dots. This means sub.foo.pagekite.me will not have TLS support, but the slightly uglier sub-foo.pagekite.me will encrypt just fine - it is up to you which you choose.

Advanced kite flying

You can fly multiple kites at once, by using the AND keyword on the command-line, like so (yes it must be capitalized):

$ pagekite.py /var/www foo.pagekite.me AND 80 foo.pagekite.me:8080

If your local web development server expects incoming requests to use localhost or foo.local in the Host: header, and you would rather not reconfigure it, pagekite.py can rewrite the header for you:

$ pagekite.py localhost:80 foo.pagekite.me +rewritehost
$ pagekite.py foo.local:80 foo.pagekite.me +rewritehost

(Note that this technique incurs a slight performance penalty and reduces compatiblity, as it disables persistent HTTP/1.1 connections.)

pagekite.py can also expose non-web services, or bind services to particular ports, and understands a familiar syntax for defining the publicly visible name.

$ pagekite.py 22 ssh:foo.pagekite.me
$ pagekite.py 3000 http://foo.pagekite.me:8080

Note that only some public-facing ports are available - consult the output from pagekite.py to get a full list. Also, accessing non-web services requires HTTP Proxy support in the client. Please consult the HowTo wiki for details.

Kite management

The definition for each kite is stored in a plain-text configuration file stored in your home directory. This file is named .pagekite.rc on Linux and the Mac, and pagekite.cfg on Windows. You can edit this file by hand, but it is generally more convenient to let pagekite.py do the work.

Some examples:

# Print a list of all configured kites and services
$ pagekite.py --list

# Add services to foo.pagekite.me:
$ pagekite.py --add /var/www foo.pagekite.me # Publish a folder
$ pagekite.py --add 80 http:foo.pagekite.me:8080 # A local webserver
$ pagekite.py --add 22 ssh:foo.pagekite.me # Enable SSH tunneling

# Disabling a service:
$ pagekite.py --disable ssh:foo.pagekite.me

# Disabling an entire kite (all services):
$ pagekite.py --disable foo.pagekite.me

# Removing kites or services completely:
$ pagekite.py --remove ssh:foo.pagekite.me
$ pagekite.py --remove foo.pagekite.me

4. More details...

Still feel like reading? Check out:

• Our support pages
• The How-To and FAQ
• The Open Source wiki pages
• The pagekite.py reference manual

Welcome to PageKite!