Installation

Horsepower can be installed multiple ways. Choosing the way you wish to install is up to you. The command line tool allows for many features that you would not otherwise receive by installing directly from git.

Command Line Tool

Horsepower can be installed using the command line tool, and having installed all of the prerequisites, creating an application is very easy using @horsepower/cli

npm install -g @horsepower/cli

Next all that needs to be done is to run the new command to create a new project

hp new hello-world

The following process will then run:

  1. A folder will be created called hello-world in the current directory
  2. Horsepower will be downloaded into the hello-world folder
  3. All of the dependencies of Horsepower will be downloaded
  4. A temporary server will be started
  5. The url http://localhost:5000 will be opened in a new browser window

You should then see the Welcome screen within your browser and if you do, everything should be working!

Git

This is the process that the command line tool does automatically.

git clone git@github.com:horsepowerjs/horsepower.git hello-world --depth 1
cd hello-world
npm install
node ./index.js

When opening a browser and navigating to http://localhost:5000, you should then see the Welcome screen within your browser and if you do, everything should be working!

Static Files

Static files are are configured to automatically be served from /public. Any files located in that directory will automatically be served when requested without the /public prefix if the file exists. If the file does not exist, then horsepower will attempt to load the request from your defined routes. If all else fails, then a 404 will be returned to the client.

Web Servers

horsepower runs on the default port 5000, so to access it you need to know the port. This is fine during development, but as a public facing website you most likely don't want that. To fix this we need to place the horsepower server behind a web server such as Nginx.

Nginx

Nginx is a fast lightweight server that is easy to use on linux servers.

First you will want to install and create a new configuration file:

# Install nginx if it hasn't already been installed
sudo apt install nginx

# Create a new configuration file
sudo vim /etc/nginx/sites-available/example.com

Within the configuration file add the following content, replacing example.com with your domain name and 5000 with the actual port that you are running the horsepower server on.

server {
  # Setup the domain name(s)
  # Each domain is separated by a space
  # Since horsepower supports domain routing, multiple domains can share the same port
  # Note: Unrelated domains should have their own port and horsepower project
  server_name example.com api.example.com;
  listen 80;

  # Setup the proxy
  # This will forward all requests to the horsepower http server
  # and then it will relay the servers response back to the client
  location / {
    proxy_pass http://127.0.0.1:5000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_cache_bypass $http_upgrade;
  }
}

We will want to create a symbolic link to this file so that we can enable/disable this domain without deleting the file itself, and just add/remove the symbolic link.

# CD to nginx "sites-enabled" directory
cd /etc/nginx/sites-enabled

# Create the symbolic link
ln -s ../sites-available/example.com ./example.com

Finally we start both of the services and test the domain (assuming it has already propagated).

# Start the horsepower http server
pm2 start /path/to/ecosystem.config.js

# Start the nginx service
sudo service nginx start

Apache

Apache is a popular server that works well on all platforms though it isn't lightweight like Nginx.

First we will start by installing apache if it hasn't already been installed, then we will create the configuration file.

# Install apache if it hasn't already been installed
sudo apt install apache2
vim /etc/apache2/sites-available/example.conf

So first we create a new virtual host, replacing example.com with your domain name and 5000 with the actual port that you are running the horsepower server on.

<VirtualHost *:80>
  # Setup the domain name(s)
  # Since horsepower supports domain routing, multiple domains can share the same port
  # Note: Unrelated domains should have their own port and horsepower project
  ServerName example.com
  ServerAlias api.example.com

  # Setup the proxy
  # This will forward all requests to the horsepower http server
  # and then it will relay the servers response back to the client
  ProxyPass http://127.0.0.1:5000
  ProxyPreserveHost On
</VirtualHost>

You must also have the modules enabled within the master apache config file:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

Finally we start both of the services and test the domain (assuming it has already propagated).

# Start the horsepower http server
pm2 start /path/to/ecosystem.config.js

# Start the apache service
sudo service apache2 start