How to set up OpenBD on a VPS

After hearing about others wanting to know how to set up OpenBD on a server, and fighting with it myself, I wanted to write a simple How-To on how to set up a simple VPS for OpenBD.

Tiago Lopo from AW2.0 helped me set up with NGINX, and it's that setup that's described here.

The basic premise for the setup I needed was; A DigitalOcean VPS running a single OpenBD instance to host multiple sites.

You can easily adjust these instructions to run multiple instance of Jetty with OpenBD if you prefer that.

Disclaimer: I'm not responsible for anything you do on your own server, I take no blame if something were to happen to your server by following this advice. There's plenty to do after setting up the basic server software, not the least of which is securing things, which is not covered in this post.

Here's what we'll be doing:
Set up a VPS
Install Java 8
Install unzip
Install OpenBD Ready2Run
Install NGINX
Set things up
Grab a beer

For this project I'm using Digital Oceans smallest Droplet, but I'm using Linode for another server, whatever you prefer should be fine.

The instructions will be as detailed as I can make them, so that anyone can follow, at least if you've spent an hour or two on a linux box before.


Assumptions
I assume that you have a domain and can point it to the VPS you're setting up.


Get started
Set up the Droplet with Ubuntu 14.04 LTS (64 bit) and wait for your login information

When the server is up, set up your domain to point to the IP, it may take a while before it takes effect so you can test it.

Log in to your VPS


Installing Java 8
Enter these commands in order, one by one:
add-apt-repository ppa:webupd8team/java
apt-get update
apt-get install oracle-java8-installer

Follow the instructions in the installer.


Install unzip
Since the OpenBD file is zipped, we need an unzip utility, enter this:
apt-get install unzip


Get Openbd nightly
First we create a folder to hold the OpenBD file:
mkdir /home/marcus

Then we cd there, and get the OpenBD file:
cd /home/marcus

wget http://openbd.org/download/nightly/jetty-openbd.zip

This can take a few minutes.

When it's done, unzip to where you want to run it from
unzip jetty-openbd.zip -d /opt/openbd

When that's run, OpenBD is technically installed!

If all you want is a single website, you could change the Jetty port from 8080 to 80 by modifying the /opt/openbd/start.ini file, uncomment and modify the line that reads # jetty.http.port=8080

cd /opt/openbd

Edit the file by using this command:
vi start.ini

Scroll down until you find that line, press the letter i on the keyboard, delete the first character, change the port to 80, press escape, then write :wq and hit enter.

To start the server, you type (from /opt/openbd/):
java -jar start.jar

If everything worked, you should be able to enter the ip of your server, or the domain name you pointed at it, and see the freshinstall page.

If you're like me, and want to run multiple sites from one OpenBD instance, read on.

I assume that you didn't change the port if you're following on.


Installing NGINX
apt-get install nginx

Easy, eh?

Now comes the hardest part (It's not actually hard), configuring NGINX to route the domain requests to the proper place, and securing Jetty to only accept connections from NGINX.


Setting everything up
This is how Tiago Lopo helped set up my server, to make it easy to extend and add sites as I go.

Rather than having a large single file containing all sites, he split it up into multiple files that are easy to copy and adjust as needed.

Create these files and add the contents, adjust URL's as needed.

To create the file you can either create locally and upload, or create on the server through SSH.

If you're on SSH, you could create the file below like so:
Copy the contents below.
Write vi /etc/nginx/conf.d/cors.conf in the console
Press i
Paste the contents, then press escape, and then :wq and press enter.

wq means write and quit.

/opt/openbd/www/mysite/index.cfm
<cfoutput>#Now()#</cfoutput>

/etc/nginx/conf.d/cors.conf
add_header 'Access-Control-Allow-Credentials' 'true';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE';
add_header 'Access-Control-Allow-Headers' 'X-Requested-With,Accept,Content-Type, Origin';

/etc/ngingx/conf.d/openbd-proxy.conf
proxy_pass  http://127.0.0.1:8080;
proxy_read_timeout 1200;
proxy_connect_timeout 75;
proxy_redirect default ;
proxy_set_header Host $host;
proxy_set_header X-RealIP $remote_addr;
add_header ServerId 0001;
proxy_intercept_errors on;

/etc/nginx/conf.d/mysite.conf
server {
        server_name mysite.marcusfernstrom.com;
        listen 80;

        location / {
                include /etc/nginx/conf.d/cors.conf;

                if ( $host = 'mysite.marcusfernstrom.com' ){
                        rewrite ^(.*)$ /mysite/$1 break;
                        proxy_pass http://127.0.0.1:8080;
                }
                include /etc/nginx/conf.d/openbd-proxy.conf;
        }
}

/etc/nginx/nginx.conf
worker_processes 1;
events {
        worker_connections 1024;
}

http{
        include                 mime.types;
        default_type            application/octet-stream;
        sendfile                on;
        keepalive_timeout       65;
        client_max_body_size    10m;
        gzip                    on;

        include /etc/nginx/conf.d/mysite.conf;
} 

Don't forget to restart nginx at this point, to make sure the settings are live.



service nginx restart

To make sure that Jetty only accepts connections from NGINX, you need to modify the /opt/openbd/start.ini file again, fine the line that reads: # jetty.http.host=0.0.0.0 and change it to jetty.http.host=127.0.0.1

The only thing left is to make sure OpenBD starts automatically when the server starts.

There are difference methods for doing this, here's what I did on this server:
 vi /etc/rc.local
 
Add these lines before exit0:
cd /opt/openbd/
java -jar start.jar
 
Save with :wq

And that's it, if things went like they should, you now have your own VPS running OpenBD, set up to handle multiple sites as virtual hosts under a single Jetty/OpenBD instance.

 If you need help or something doesn't work right, stop by the Google group at https://groups.google.com/forum/#!forum/openbd, I'm happy to try helping you, but know that I'm not expert when it comes to Jetty or NGINX. 

Learning Java, and OpenBD plugins

I've wanted to work with the OpenBD engine itself for a long time, the idea of being able to extend it sounded both fun and useful but there were two things working against me.

1. I didn't know Java
2. I didn't know how to make plugins or modify the engine

I can't say that I know Java now, but I'm learning and at a pretty decent rate I think.

I just can't do "Hello World" over and over, so I wanted to do something real, and then I saw someone on the google group ask if we could have a function added to the engine, isUserLoggedIn()

Now, knowing what the function does, I figured that's about as easy as it gets, so I started digging and figured out (With some help) how to register functions and whatnot, and created the isUserLoggedIn() function, made a pull request on GitHub and it was accepted, my code is now in the engine    :)

The next step was to figure out how to make plugins, as some of my ideas aren't a good fit for getting added to the engine itself.

Andy Wu with AW2.0 suggested that I look at an existing plugin to get an idea of how they work, and with his help I managed to get up and running, and created a plugin that uses a Mashape API for converting strings of text into Yoda-speak.

Not a very useful plugin, but not only was it a real plugin, it talked to an external API, so kind of cool.

Today I released my first "real" plugin, one that's a bit more useful.

Something I've always wanted was the ability to create barcodes, and now I finally created a plugin for that purpose.

Tadaa:  https://github.com/MFernstrom/barcode-plugin

It uses the barcode4j for regular barcodes, and ZXing library for generating QR codes.

The images are saved to disk, and the function returns a boolean true if all went well.

I'm learning Java the same way I taught myself CFML, by doing things for real, and I'm having a blast.

I'm open to ideas about things the community would like to have, if it's doable and sounds like fun I'll likely take a stab at creating it, be it functions, improvements or plugins.

For anyone else thinking about getting into making plugins, all I can say is: DO EEET!

It's fun, and is a natural progression for a CFML dev wanting to continue on the path, since the engines are all written in Java.