OC From Scratch

This repo contains the resources to setup your own OpenChirp instance from scratch. We will walk through a typical install on Debian.

Steps

• Install Dependencies
  • Setup additional Debian sources
  • Install the openchirp-dep package
• System Preparations
  • Create openchirp system user
  • Setup SSL Certificates
• Setup OpenChirp REST Server and Website
  • Setup OAUTH
  • Setup and Build Website
    • Checkout
    • Config
    • Build
    • Copy
  • Setup REST server
    • Checkout
    • Config
    • NPM Install
    • Sytemd
• Setup Apache2 for Website and REST
  • Enable modules
  • Add site config
  • Enable site
• Optional Config
  • Add users manually to Mosquitto

Install Dependencies

Setup additional Debian sources

Add nodesource.list file to /etc/apt/source.list.d/ with the following contents:

# Supports OpenChirp V1.0
deb https://deb.nodesource.com/node_10.x stretch main
deb-src https://deb.nodesource.com/node_10.x stretch main

Add influxdb.list file to /etc/apt/source.list.d/ with the following contents:

# Supports OpenChirp V1.0
deb https://repos.influxdata.com/debian buster stable

Add loraserver.list file to /etc/apt/source.list.d/ with the following contents:

# Supports OpenChirp V1.0
deb https://artifacts.loraserver.io/packages/1.x/deb stable main

Then add the Nodesource, Influxdb, and LoRaServer repo key to apt-key.

wget -qO- https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -
wget -qO- https://repos.influxdata.com/influxdb.key | sudo apt-key add -
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00

Install the openchirp-dep package

sudo dpkg -i packages/openchirp-dep/openchirp-dep_1.5_all.deb
sudo apt-get update
sudo apt-get install -f

System Preparations

Create openchirp system user

sudo adduser --system --no-create-home --disabled-login openchirp

Setup SSL Certificates

sudo certbot certonly --rsa-key-size 4096 --webroot --webroot-path /var/www/testing.openchirp.io -d testing.openchirp.io -d www.testing.openchirp.io

Setup OpenChirp REST Server and Website

Setup OAUTH

Please login to the Google Developer Console and generate an OAUTH key.

Setup and Build Website

ng build

Setup REST server

Clone openchirp_rest into /srv/

cd /srv
sudo git clone https://github.com/OpenChirp/openchirp_rest.git

In the openchirp_rest directory, run npm install

Setup Systemd for REST server

Click to view `openchirp-rest.service`

[Unit]
Description=OpenChirp REST framework server
Documentation=https://openchirp.io
After=network.target

[Service]
Environment=NODE_ENV=production
Environment=PORT=7000
Type=simple
User=openchirp
WorkingDirectory=/srv/openchirp_rest/bin
ExecStart=/srv/openchirp_rest/bin/www
Restart=on-failure

[Install]
WantedBy=multi-user.target
Alias=rest.service

Setup Apache2 for Website and REST

sudo a2enmod ssl
sudo a2enmod proxy
sudo a2enmod proxy_http

Create /etc/apache2/sites-available/testing.openchirp.io.conf

Click to view `testing.openchirp.io.conf`

<VirtualHost *:80>
	# The ServerName directive sets the request scheme, hostname and port that
	# the server uses to identify itself. This is used when creating
	# redirection URLs. In the context of virtual hosts, the ServerName
	# specifies what hostname must appear in the request's Host: header to
	# match this virtual host. For the default virtual host (this file) this
	# value is not decisive as it is used as a last resort host regardless.
	# However, you must set it for any further virtual host explicitly.
	ServerName testing.openchirp.io
	ServerAlias www.testing.openchirp.io

	ServerSignature Off
	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/testing.openchirp.io


	#Redirect permanent "/" "https://testing.openchirp.io/"
	# Redirect all requests to https site, unless it is a certbot
	# HTTP-01 challenge request.
	# This regex has been carefully crafted by Craig.
	RedirectMatch permanent "^(?!/\.well-known/acme-challenge/[\w-]{43}$)(.*)$" "https://testing.openchirp.io$1"

 	<Directory "/var/www/testing.openchirp.io">
		RewriteEngine on

		# Don't rewrite files or directives
		RewriteCond %{REQUEST_FILENAME} -f [OR]
		RewriteCond %{REQUEST_FILENAME} -d
		RewriteRule ^ - [L]

		#Rewrite everything else to index.html to allow html5 state links
		RewriteRule ^ index.html [L]
	</Directory>

	# error, crit, alert, emerg.
	# It is also possible to configure the loglevel for particular
	# modules, e.g.
	#LogLevel info ssl:warn
	LogLevel info

	ErrorLog ${APACHE_LOG_DIR}/testing_openchirp_io_error.log
	CustomLog ${APACHE_LOG_DIR}/testing_openchirp_io_access.log combined

	# For most configuration files from conf-available/, which are
	# enabled or disabled at a global level, it is possible to
	# include a line for only one particular virtual host. For example the
	# following line enables the CGI configuration for this host only
	# after it has been globally disabled with "a2disconf".
	#Include conf-available/serve-cgi-bin.conf
</VirtualHost>

<IfModule mod_ssl.c>
	<VirtualHost _default_:443>
		ServerName testing.openchirp.io:443
		ServerAlias www.testing.openchirp.io
		ServerAdmin webmaster@localhost
		ServerSignature Off

		DocumentRoot /var/www/testing.openchirp.io

		# Latest REST/auth api
		ProxyPass "/api" "http://localhost:7000/api"
		ProxyPassReverse "/api" "http://localhost:7000/auth"
		ProxyPass "/pc" "http://localhost:7000/pc"
		ProxyPassReverse "/pc" "http://localhost:7000/pc"
		ProxyPass "/auth" "http://localhost:7000/auth"
		ProxyPassReverse "/auth" "http://localhost:7000/auth"

		# REST/auth api v1
		ProxyPass "/apiv1" "http://localhost:7000/api"
		ProxyPassReverse "/apiv1" "http://localhost:7000/api"
		ProxyPass "/pcv1" "http://localhost:7000/pc"
		ProxyPassReverse "/pcv1" "http://localhost:7000/pc"
		ProxyPass "/authv1" "http://localhost:7000/auth"
		ProxyPassReverse "/authv1" "http://localhost:7000/auth"


		# Latest Mapper
		ProxyPass "/mapper" "http://localhost:9000"
		ProxyPassReverse "/mapper" "http://localhost:9000"

		# Latest Grafana
		ProxyPass "/grafana" "http://localhost:3000"
		ProxyPassReverse "/grafana" "http://localhost:3000"

		<Directory "/var/www/testing.openchirp.io">
			RewriteEngine on

			# Don't rewrite files or directives
			RewriteCond %{REQUEST_FILENAME} -f [OR]
			RewriteCond %{REQUEST_FILENAME} -d
			RewriteRule ^ - [L]

			#Rewrite everything else to index.html to allow html5 state links
			RewriteRule ^ index.html [L]
		</Directory>

		# Redirect everything to openchirp.io
		<If "%{HTTP_HOST} != 'testing.openchirp.io'">
			Redirect permanent "/" "https://testing.openchirp.io/"
		</If>

		# Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
		# error, crit, alert, emerg.
		# It is also possible to configure the loglevel for particular
		# modules, e.g.
		#LogLevel info ssl:warn

		ErrorLog ${APACHE_LOG_DIR}/testing_openchirp_io_ssl_error.log
		CustomLog ${APACHE_LOG_DIR}/testing_openchirp_io_ssl_access.log combined

		# For most configuration files from conf-available/, which are
		# enabled or disabled at a global level, it is possible to
		# include a line for only one particular virtual host. For example the
		# following line enables the CGI configuration for this host only
		# after it has been globally disabled with "a2disconf".
		#Include conf-available/serve-cgi-bin.conf

		#   SSL Engine Switch:
		#   Enable/Disable SSL for this virtual host.
		SSLEngine on

		#   A self-signed (snakeoil) certificate can be created by installing
		#   the ssl-cert package. See
		#   /usr/share/doc/apache2/README.Debian.gz for more info.
		#   If both key and certificate are stored in the same file, only the
		#   SSLCertificateFile directive is needed.
		#SSLCertificateFile	/etc/ssl/certs/ssl-cert-snakeoil.pem
		#SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
		SSLCertificateFile    /etc/letsencrypt/live/testing.openchirp.io/fullchain.pem
		SSLCertificateKeyFile /etc/letsencrypt/live/testing.openchirp.io/privkey.pem
		Include /etc/letsencrypt/options-ssl-apache.conf

		#   Server Certificate Chain:
		#   Point SSLCertificateChainFile at a file containing the
		#   concatenation of PEM encoded CA certificates which form the
		#   certificate chain for the server certificate. Alternatively
		#   the referenced file can be the same as SSLCertificateFile
		#   when the CA certificates are directly appended to the server
		#   certificate for convinience.
		#SSLCertificateChainFile /etc/apache2/ssl.crt/server-ca.crt

		#   Certificate Authority (CA):
		#   Set the CA certificate verification path where to find CA
		#   certificates for client authentication or alternatively one
		#   huge file containing all of them (file must be PEM encoded)
		#   Note: Inside SSLCACertificatePath you need hash symlinks
		#		 to point to the certificate files. Use the provided
		#		 Makefile to update the hash symlinks after changes.
		#SSLCACertificatePath /etc/ssl/certs/
		#SSLCACertificateFile /etc/apache2/ssl.crt/ca-bundle.crt

		#   Certificate Revocation Lists (CRL):
		#   Set the CA revocation path where to find CA CRLs for client
		#   authentication or alternatively one huge file containing all
		#   of them (file must be PEM encoded)
		#   Note: Inside SSLCARevocationPath you need hash symlinks
		#		 to point to the certificate files. Use the provided
		#		 Makefile to update the hash symlinks after changes.
		#SSLCARevocationPath /etc/apache2/ssl.crl/
		#SSLCARevocationFile /etc/apache2/ssl.crl/ca-bundle.crl

		#   Client Authentication (Type):
		#   Client certificate verification type and depth.  Types are
		#   none, optional, require and optional_no_ca.  Depth is a
		#   number which specifies how deeply to verify the certificate
		#   issuer chain before deciding the certificate is not valid.
		#SSLVerifyClient require
		#SSLVerifyDepth  10

		#   SSL Engine Options:
		#   Set various options for the SSL engine.
		#   o FakeBasicAuth:
		#	 Translate the client X.509 into a Basic Authorisation.  This means that
		#	 the standard Auth/DBMAuth methods can be used for access control.  The
		#	 user name is the `one line' version of the client's X.509 certificate.
		#	 Note that no password is obtained from the user. Every entry in the user
		#	 file needs this password: `xxj31ZMTZzkVA'.
		#   o ExportCertData:
		#	 This exports two additional environment variables: SSL_CLIENT_CERT and
		#	 SSL_SERVER_CERT. These contain the PEM-encoded certificates of the
		#	 server (always existing) and the client (only existing when client
		#	 authentication is used). This can be used to import the certificates
		#	 into CGI scripts.
		#   o StdEnvVars:
		#	 This exports the standard SSL/TLS related `SSL_*' environment variables.
		#	 Per default this exportation is switched off for performance reasons,
		#	 because the extraction step is an expensive operation and is usually
		#	 useless for serving static content. So one usually enables the
		#	 exportation for CGI and SSI requests only.
		#   o OptRenegotiate:
		#	 This enables optimized SSL connection renegotiation handling when SSL
		#	 directives are used in per-directory context.
		#SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
		<FilesMatch "\.(cgi|shtml|phtml|php)$">
				SSLOptions +StdEnvVars
		</FilesMatch>
		<Directory /usr/lib/cgi-bin>
				SSLOptions +StdEnvVars
		</Directory>

		#   SSL Protocol Adjustments:
		#   The safe and default but still SSL/TLS standard compliant shutdown
		#   approach is that mod_ssl sends the close notify alert but doesn't wait for
		#   the close notify alert from client. When you need a different shutdown
		#   approach you can use one of the following variables:
		#   o ssl-unclean-shutdown:
		#	 This forces an unclean shutdown when the connection is closed, i.e. no
		#	 SSL close notify alert is send or allowed to received.  This violates
		#	 the SSL/TLS standard but is needed for some brain-dead browsers. Use
		#	 this when you receive I/O errors because of the standard approach where
		#	 mod_ssl sends the close notify alert.
		#   o ssl-accurate-shutdown:
		#	 This forces an accurate shutdown when the connection is closed, i.e. a
		#	 SSL close notify alert is send and mod_ssl waits for the close notify
		#	 alert of the client. This is 100% SSL/TLS standard compliant, but in
		#	 practice often causes hanging connections with brain-dead browsers. Use
		#	 this only for browsers where you know that their SSL implementation
		#	 works correctly.
		#   Notice: Most problems of broken clients are also related to the HTTP
		#   keep-alive facility, so you usually additionally want to disable
		#   keep-alive for those clients, too. Use variable "nokeepalive" for this.
		#   Similarly, one has to force some clients to use HTTP/1.0 to workaround
		#   their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and
		#   "force-response-1.0" for this.
		# BrowserMatch "MSIE [2-6]" \
		#		nokeepalive ssl-unclean-shutdown \
		#		downgrade-1.0 force-response-1.0

	</VirtualHost>
</IfModule>

# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

Then activate the site.

sudo a2ensite testing.openchirp.io.conf
sudo systemctl restart apache2

Optional Config

Add users manually to Mosquitto

You can add manual users to Mosquitto (using auth plugin) by adding their username into the /etc/mosquitto/passwords.pbkdf2 file followed by a : and the PBKDF2 hash generated by the np command. The np command only needs the password. You can run the following command to generate the password has:

np -p 'YourPasswordHere'

Entries in the password.pbkdf2 file are of the form <username>:<hash_from_np_command>. For example, here is one entry for the user jane.

jane:PBKDF2$sha256$901$wvvH0fe7Ftszt8nR$NZV6XWWg01dCRiPOheVNsgMJDX1mzd2v

Next, you need to make an associated acl in the /etc/mosquitto/acls.conf file.

An acl entry to give jane full access would be the following:

user jane
topic #

See https://github.com/jpmens/mosquitto-auth-plug for more information about the mosquitto auth plugin.