Now that you’ve got Pushpin installed and running, it’s time to have some fun with it!
Pushpin comes with a mock backend so that you don’t need to set up a real backend web service in order to try it out. Confirm that your routes file contains a single line that looks like this:
* test
By default, Pushpin listens for connections on port 7999. Connect to the server with an HTTP client, such as curl:
curl http://localhost:7999/stream
The /stream endpoint is served by the test handler, which instructs Pushpin to subscribe the connection to a channel called test.
Publish data to the connection like this:
pushpin-publish test "hello there"
Any connected clients will receive the line “hello there”. Ta-da, realtime push!
You can also publish data using a simple HTTP request:
curl -d '{ "items": [ { "channel": "test", "formats": {
"http-stream": { "content": "hello there\n" } } } ] }' \
http://localhost:5561/publish/
Please note that the test handler is only intended for experimentation. The proper way to handle client connections in a real application is to set up proxying to a backend web service. This is described in the next section.
Now let’s try adding an HTTP streaming endpoint to an existing web service.
Configure Pushpin to route traffic to your web service backend instead of the test handler. For example, if your backend listens on port 8000 of your local machine, change the routes file to contain this line:
* localhost:8000
Confirm that you are able to make HTTP requests through Pushpin to your backend. Until the backend is modified to respond with special instructions, requests and responses simply pass through.
Make an endpoint on the backend respond with two additional HTTP headers: Grip-Hold and Grip-Channel. The headers could be served by a new endpoint, or served optionally by an existing endpoint given certain conditions (e.g. if a special query string is supplied). For example, an endpoint could respond as such:
HTTP/1.1 200 OK
Content-Type: text/plain
Grip-Hold: stream
Grip-Channel: test
This is enough for clients to connect and get a long-lived connection.
Publish data to the connection the same way as in the previous section:
pushpin-publish test "hello there"
For more details, see the Usage section. Pushpin supports other push transports, too.
Pushpin has two primary configuration files: pushpin.conf and routes. It is generally not necessary to edit pushpin.conf. You’ll spend more time with the routes file.
A simple routes file might look something like this:
* localhost:8000
This means route any incoming HTTP request or WebSocket connection to an origin server running on port 8000 of the local machine.
If you want to handle WebSocket connections using a regular HTTP server, then specify the over_http option on the destination:
* localhost:8000,over_http
Pushpin monitors the routes file for changes, so you can edit the file and the changes will take effect without a restart.
For more more information about configuring Pushpin, see Configuration.
We recommend watching the walkthrough video below. It shows how to build basic HTTP streaming and WebSocket services using PHP, curl, and wscat.