#pkgr

A sample rails application

We will start by preparing a new Rails 3.2 application (Rails 4 is still too recent), using thin as the application server.

$ mkdir PkgrTest && cd PkgrTest $ cat <<EOF > Gemfile source 'https://rubygems.org' gem 'rails', '~> 3.2.13' EOF $ bundle install $ bundle exec rails new . -d sqlite3 --skip-bundle # say yes when asked to overwrite Gemfile $ sed -i -e "s/unicorn/thin/g" -e "s/# gem 'thin'/gem 'thin'/g" Gemfile # pkgr only supports thin as app server for the time being $ sed -i -e "s/# gem 'therubyracer'/gem 'therubyracer'/g" Gemfile # we will need support for precompiled assets $ bundle $ git init . $ git add . $ git commit -m "Initial commit"

Customizing the application

Now that we have a skeleton application, let's make it a little more useful. We would like to manage our collection of videos, so we add a simple "Video" model using the Rails generator. We will also set the application routes to open the videos controller.

$ bundle exec rails generate scaffold Video title:string rating:integer notes:text $ echo >> db/seeds.rb "Video.create(title: 'Toy Story', rating: 5, notes: 'Famous for naming its characters after the Debian releases')" $ bundle exec rake db:migrate db:seed $ sed -i -e "s/# root :to.*$/root :to => 'videos#index'/" config/routes.rb $ git rm public/index.html # to use "root" action in routes.rb instead of rails placeholder $ bundle exec rails server

After performing all these steps, let's open http://localhost:3000 and check that our application is working as intended. We are still in development mode.

All good?

$ git add . $ git commit -m "added video resource"

Now let's see how easily we can package our application using pkgr.

Packaging the application

First, let's enable pkgr in our Gemfile. We will restrict it to the development group since we are not packaging anything while running in production.

$ echo "gem 'pkgr', :group => :development" >> Gemfile $ bundle $ git add Gemfile* $ git commit -m "now with pkgr"

Now we can build the application package.

$ bundle exec pkgr --uri . --bump 0.1.0 --host [email protected]

Did you notice the explicit build.host option? To build the native package, pkgr installs multiple dependencies and runs different commands, some of them as root. This is why using a disposable virtual machine for building is recommended.

We could also use localhost as the build host, as long as we are already running Debian or Ubuntu and have password-less sudo (pkgr could improve its sudo prompt detection to catch up with capistrano). This is why we explicitly specify --host [email protected], where build.host points to a disposable Debian installation.

Good to know: pkgr requires to manage the application's source code with git. The reason is that pkgr uses its own branch to inject its own configuration and support files over the application's codebase. This is quite a good idea, as this build branch can safely be removed once the packaging is done without contaminating the original code.

For experts: check the step by step instructions. It may be useful to specify extra dependencies, add custom scripts etc.

After running the build for a while, we find out that the package won't build, because pkgr used the Rails directory name ('PkgrTest') as the default package name and Debian complains about names that contains with capitalized letters. We could learn how to specify a custom package name but we are pragmatic and chose to rename the Rails directory instead.

$ cd .. $ mv PkgrTest pkgr-test $ cd pkgr-test

After rebuilding, we finally obtain a package in pkg/pkgr-test_0.1.0-1_amd64.deb.

Let's inspect it!

$ dpkg --info pkg/pkgr-test_0.1.0-1_amd64.deb new debian package, version 2.0. size 15328942 bytes: control archive= 143100 bytes. 146 bytes, 6 lines conffiles 342 bytes, 8 lines control 671952 bytes, 5057 lines md5sums 1834 bytes, 67 lines * postinst #!/bin/sh 164 bytes, 7 lines * postrm #!/bin/sh 1304 bytes, 62 lines * prerm #!/bin/sh Package: pkgr-test Version: 0.1.0-1 Architecture: amd64 Maintainer: Julien Pervillé <[email protected]> Installed-Size: 58599 Depends: libc6 (>= 2.15), libgcc1 (>= 1:4.1.1), libruby1.9.1 (>= 1.9.3~rc1), libsqlite3-0 (>= 3.6.11), libstdc++6 (>= 4.1.1), ruby1.9.1-full, git-core, libxml2, libxslt1.1 Section: unknown Priority: extra $ dpkg --contents pkg/pkgr-test_0.1.0-1_amd64.deb # ... lots of files listed drwxr-xr-x root/root 0 2013-07-20 00:15 ./var/log/ drwxr-xr-x root/root 0 2013-07-20 00:15 ./var/log/pkgr-test/ lrwxrwxrwx root/root 0 2013-07-20 00:15 ./opt/local/pkgr-test/db -> /var/db/pkgr-test lrwxrwxrwx root/root 0 2013-07-20 00:15 ./opt/local/pkgr-test/log -> /var/log/pkgr-test lrwxrwxrwx root/root 0 2013-07-20 00:15 ./opt/local/pkgr-test/config/pkgr.yml -> /etc/pkgr-test/pkgr.yml lrwxrwxrwx root/root 0 2013-07-20 00:15 ./opt/local/pkgr-test/config/database.yml -> /etc/pkgr-test/database.yml

Let's see if the new package installs on a clean machine.

$ scp pkg/pkgr-test_0.1.0-1_amd64.deb [email protected]: $ ssh [email protected] 'sudo dpkg -i pkgr-test_0.1.0-1_amd64.deb || sudo apt-get -f -y install'

Open http://production.host:8000 (pkgr configures the application server to listen on port 8000 by default). We are welcomed by a "500" error page. A quick look at /var/log/pkgr-test on the production target shows us that we need to setup the database.

$ ssh [email protected] 'sudo pkgr-test rake db:migrate' $ ssh [email protected] 'sudo pkgr-test server restart'

Since we have experience with Rails, we use the opportunity to precompile the assets before getting another "500" error.

# sudo -u pkgr-test sh -c 'cd /opt/local/pkgr-test && bundle exec rake assets:precompile'

Please note: there is a pkgr branch to support asset precompilation but not merged yet.

Integrating into a virtualhost

pkgr packages the Rails application, creates the application user, setup directories, log rotation and init scripts, but it does not configure the frontend web server (apache or nginx) to forward traffic to it.

To finish the job, we will configure an nginx virtualhost for the application. I don't know yet if such a virtualhost can be easily added to pkgr but it would be a nice feature to have, for sure.

# on the production host $ sudo apt-get install nginx $ sudo cat <<EOF > /etc/nginx/sites-available/pkgr-test server { listen *:80 default_server; #server_name pkgr-test.example.com; server_tokens off; # don't show the version number, a security best practice root /opt/local/pkgr-test/public; # individual nginx logs for this gitlab vhost access_log /var/log/pkgr-test/nginx_access.log; error_log /var/log/pkgr-test/nginx_error.log; location / { # serve static files from defined root folder;. try_files $uri \$uri/index.html \$uri.html @upstream; } location @upstream { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_set_header X-Forwarded-Proto \$scheme; proxy_set_header Host \$http_host; proxy_set_header X-Real-IP \$remote_addr; proxy_pass http://localhost:8000; } # if the request is for a static resource, nginx should serve it directly # and add a far future expires header to it, making the browser # cache the resource and navigate faster over the website. location /assets { expires max; add_header Cache-Control public; break; } error_page 500 502 503 504 /50x.html; location = /50x.html { root html; } } EOF $ sudo rm /etc/nginx/sites-enabled/default $ sudo ln -s /etc/nginx/sites-available/pkgr-test /etc/nginx/sites-enabled/pkgr-test $ sudo service nginx restart

Now we can go back to our browser and enjoy the application in production. If we update the application's code, we can run a pkgr build again, but it should go much faster.

We found a few bugs and gotchas in the process and it took more than 5 minutes to turn the Rails application into a package, but we still saved us a lot of time and had fun while at it. Thank you pkgr!

Conclusion

I liked the idea of easily building a native package from a Rails application. I also appreciate that pkgr provides default control and init scripts, logrotate rules etc. to make the Rails application play well with the operating system.

However, I believe that the choices taken by the author are a bit limiting and that more potential for customization would be useful. I'd love to have a better control script, use puma as application server or add monit rules to watch my application as I install it.

The build process could also be more robust, as I had to struggle quite a lot to build my packages (sudo prompt detection issues, network issues during downloads etc). In general, the build script only works in the happy path and is completely lost when one of the steps fails.