Meteor

An HTTP server for the 2.0 web

Welcome to Meteor - you're a star! (Learn more)

Meteor home > Installation

1. Download and unpack

This installation will assume that you're running some flavour of linux with perl 5 already installed. Create a directory from which you want to run Meteor (/usr/local/meteor is suggested), cd into it, and issue the following command to download the latest source, unpack it, and delete the tar file:

You will then have the following in your /usr/local/meteor directory:

2. Configure

Copy the init script to /etc/init.d/meteord:

You will need to edit the file to change the path if you did not install meteor in /usr/local/meteor. If you wish to use this to start/stop Meteor, you will need to edit line 14 to specify which user account will be used to run it. The default is meteor, so if you want to create that user account now, type:

Now copy the configuration file to /etc/meteord.conf:

If you want to, open up the file and have a look (see the server documentation for more details). Don't edit anything at this stage otherwise it'll muck up the rest of this tutorial.

If you want Meteor to start on system boot, run the following command:

Help! I did that and Meteor is still not running on boot

If you find that Meteor isn't running automatically on boot, and Meteor's log output says 'sudo: sorry, you must have a tty to run sudo', then you need to comment out the following line in /etc/sudoers:

This appears to be a change in behaviour between Fedora Core 5 and Fedora Core 6, though of course may affect other Linux distributions.

Help! I get -bash: ./meteord: Permission denied

That's because, for some reason, meteord is not executable. Run the following command to fix that:

3. Run Meteor

Start Meteor in the foreground and get debug output:

For reference, to manually start Meteor as a background process, you'd do this:

Help! When I do that I get /etc/init.d/functions: No such file or directory

All our development is done on Fedora, which includes a functions file to enable startup scripts to be a bit prettier. Frankly, all it provides is the ability to print [ OK ] in green, or [ Failed ] in red.

Suggest you simply update the script such that line 6 is removed, and any reference to "&& success || failure" is removed, or use whatever system is preferred on your chosen linux distribution (and if you do, let us know and we'll document it here).

4. Test subscriber connections

Before you start setting up your web pages with the Meteor JavaScript client, take a minute to check that the server is running. Open up your favourite terminal program (we use PuTTY) and connect to the IP on which Meteor is listening (any IP or hostname that resolves to the machine on which Meteor is running), using port 4670. Ensure you're making a raw TCP connection - in PuTTY, select 'Raw' as the protocol. Type the following line and press enter twice:

If all is well you should see the following output:

You should also see an extra ping snippet (<script>p(-1,"");</script>) being appended about every 3 seconds. Leave it running. You'll also see something like this appear in the shell in which you're running Meteor in debug mode:

5. Test controller connections

Now check that you can inject a message successfully onto the test channel. Open another terminal window and connect to Meteor on its controller interface (again, any IP or hostname that resolves to the machine on which Meteor is running), this time on port 4671. Type the following command:

Meteor should respond OK and if you've still got your subscriber connection open, you should see the following message suddenly appear in that window:

Voila. You just made Meteor stream a message to you. Finally, you'll also see stuff in the debug output of the shell in which you're running Meteor:

For full details of the event controller command protocol, see the server documentation. To create a real-life useful event controller, you just need to write a program to make a socket connection as you just did with your terminal, and fire ADDMESSAGE commands down it. See the examples page for some complete examples and code.

You can close the terminal sessions now, and stop Meteor.

6. Integrate with web server

Here's the tricky bit. You'll want to serve your website on port 80, obviously, and to avoid cross-site scripting restrictions, Meteor must also serve on the same port. So you have three possible approaches to making this happen:

  1. Set SubscriberPort to 80 and SubscriberIP to a specific IP, say X.X.X.1, in the Meteor config file. This will bind Meteor to a particular IP address on port 80 and leave Apache to bind to port 80 on a different IP. To make this work you will need to run Meteor as root, and configure Apache (or whatever web-server you're using) to bind to port 80 on a different IP, say X.X.X.2.
  2. Configure a firewall to redirect traffic on port 80 of one specific IP, to the Meteor Subscriber port (typically 4670). Then both Meteor and Apache can run in their default configurations, and Meteor can be run as a non-privileged user. So, if you're using iptables you need the following commands: or if you've got a hardware firewall, set up an equivilent set of rules on that.
  3. Run Meteor on a different physical server to the one running Apache. Then each server need only have one IP, and Apache can be run in its default configuration. Meteor must be set to use port 80 and be run as root.

Since it's likely that the events that you are streaming to your users will be generated by other users of the site, there is a strong argument for having the Meteor server on the same physical machine as your web server. That is, unless you're operating a major site with a multiple server architecture, in which case you can choose whether to have Meteor on each web cluster machine, or have a separate cluster of Meteor servers.

Help! How do I assign multiple IP addresses to a single network card?

Windows, Linux, and Mac OS X all support the assignment of multiple IP addresses to a single NIC. We're assuming you're using Linux, so this is actually pretty easy, just add more addresses using ifconfig:

Provided that both addresses are within your machine's subnet, you should be sorted.

7. Configure DNS

Set up your domain's DNS records with two records, as in the following example:

example.comAINY.Y.Y.Y (IP for Apache)
data.example.comAINX.X.X.X (IP for Meteor)

The IPs for Meteor and Apache may actually be assigned to the same physical server, which will be the case with either option (1) or (2) above, but it's vital that the requests are separated out by IP so that the correct server receives them.

Of course you will probably also want a www. record, and that can simply resolve to Apache as well. The data. subdomain in this example assumes that you then set the host property of the Meteor JavaScript client to data.example.com. You can actually use any host that you want, provided that you set the value of the JavaScript host property to the same thing, and it's a subdomain of your Apache host.

8. Test static file serving

Whilst most of the web client javascript Meteor uses is contained in the meteor.js class, there are also specific bits of Javascript that are downloaded by the class at runtime from the Meteor server. It's important to ensure that this process is working, which will confirm that Meteor is running, and that you've set up the SubscriberDocumentRoot config parameter to correctly point at the location of the stream.html and poll.html files (this should be the case if you've done everything as specified in this tutorial).

Open your favourite web browser (or simply use curl) and download (replacing example.com with your domain):

You should receive a page of javascript code (you may have to view source to see it).

8. Use Meteor in your web application!

Now that you have Meteor running alongside your preferred web server, all you need to do is create your web application. To include Meteor in your web pages, add the following Javascript include to the header:

Then when you want to start streaming, do something like:

For full details of the javascript class API, see the JS client documentation. See the examples page for some complete examples and code.