pkgr 0.1.1 → 0.2.0

data/README.md

@@ -2,7 +2,7 @@
 
 Plug this [Railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html)
 into your Rails 3 app (ruby1.9 only), and you'll be ready to package your
-Rails app as a DEB or RPM (coming soon) package.
+Rails app as a DEB package. RPM support could be added in the short future.
 
 ## Why?
 
@@ -37,7 +37,7 @@ So, how are we going to easily package Ruby applications and avoid dependency
 issues? Well, I know package maintainers will scream at me, but we'll just
 vendor the required gems in the package we'll build, and use bundler to manage
 those dependencies. Thus, the only dependency we'll put in our package will be
-the Ruby1.9 (+rubygems).
+Ruby1.9 (+rubygems).
 
 ## What?
 
@@ -50,13 +50,271 @@ few other things.
 The default target installation directory for the other app files will be
 `/opt/local/app-name`. This can be configured.
 
-## Usage
+## Requirements
+
+* You must use Rails3+ and ruby1.9+ in your application. This may work with
+  other rubies but then you'll need to add a rubygems dependency.
+
+* Your Rails application must be able to run with the
+  [`thin`](http://code.macournoyer.com/thin/) web server. Don't forget to add
+  `thin` to your Gemfile!
+
+* Your application must be checked into a **Git** repository. Your name and
+  email is taken from the git configuration, and the changelog is populated
+  based on the git log between two versions.
+
+## Getting started
+
+Or, how to build a debian package of your Rails app in 5 minutes.
+
+### Setup
+
+Create a new Rails app:
+
+    $ rails new my-app --skip-bundle
+          create  
+          create  README.rdoc
+          create  Rakefile
+          ...
+          create  vendor/plugins
+          create  vendor/plugins/.gitkeep
+
+Go into your app directory, and add `pkgr` to your Gemfile:
+
+    $ cd my-app
+    $ echo "gem 'pkgr', :group => :development" >> Gemfile
+
+For now, this packaging tool only supports `thin` (would be easy to add others, though), so add it to your Gemfile:
+
+    $ echo "gem 'thin'" >> Gemfile
+
+Install the gems:
+
+    $ bundle install
+
+If it's not already done, initialize a git repository and create a first commit:
+
+    $ git init
+    $ git add .
+    $ git commit -m "First commit"
+
+Setup `pkgr`:
+
+    $ rake pkgr:setup
+    Setting up configuration file...
+    ...
+    Edit '/Users/crohr/tmp/my-app/config/pkgr.yml' and fill in the required information, then enter 'rake pkgr:generate' to generate the debian files.
+
+As outlined, edit `config/pkgr.yml` and fill in your app name. In our example I'll fill in `my-app` as the app name. Also, you should edit the runtime and build dependencies (though the default ones should be fine with a base Rails app).
+
+An example `pkgr.yml` file is given below:
+
+    ---
+    version: 0.4.0
+    name: my-app
+    description: This is a description
+    git_ref: HEAD
+    config_files:
+    - pkgr.yml
+    - database.yml
+    architecture: amd64
+    debian_runtime_dependencies:
+    - ${shlibs:Depends}
+    - ${misc:Depends}
+    - ruby1.9.1-full
+    - git-core
+    - libxml2
+    - libxslt1.1
+    debian_build_dependencies:
+    - debhelper (>= 7)
+    - dpkg-dev
+    - libmysqlclient15-dev
+    - libxml2-dev
+    - libxslt-dev
+    - libsqlite3-dev
+
+### Generate the packaging files
+
+Now generate the required files for packaging:
+
+    $ rake pkgr:generate
+    mkdir -p /Users/crohr/tmp/my-app/debian
+    cp /Users/crohr/.rvm/gems/ruby-1.9.3-p125/gems/pkgr-0.1.0/lib/pkgr/data/debian/changelog /Users/crohr/tmp/my-app/debian/changelog
+    cp /Users/crohr/.rvm/gems/ruby-1.9.3-p125/gems/pkgr-0.1.0/lib/pkgr/data/debian/cron.d /Users/crohr/tmp/my-app/debian/cron.d
+    Correctly set up debian files.
+    mkdir -p /Users/crohr/tmp/my-app/bin
+    cp /Users/crohr/.rvm/gems/ruby-1.9.3-p125/gems/pkgr-0.1.0/lib/pkgr/data/bin/executable /Users/crohr/tmp/my-app/bin/my-app
+    chmod 755 /Users/crohr/tmp/my-app/bin/my-app
+    Correctly set up executable file. Try running './bin/my-app console'.
+
+This will have created the required `debian/` files, plus an executable for your app, so that you're able to do the following:
+
+    $ ./bin/my-app console development
+    $ ./bin/my-app server start -e development
+    $ ./bin/my-app rake some_task
+
+This is especially useful when the app is deployed on a server, since the executable will be added to the path!
+
+By default, you should not have to change anything in the `debian/` folder, so let's package our app. 
+
+### Package the app
+
+First, make sure you committed all your changes:
+
+    $ git add .
+    $ git commit -m "..."
+
+Then increase the version number:
+
+    $ rake pkgr:bump:minor
+    Committing changelog and version file...
+    git add debian/changelog /Users/crohr/tmp/my-app/config/pkgr.yml && git commit -m 'v0.1.0' debian/changelog /Users/crohr/tmp/my-app/config/pkgr.yml
+    [master c05dd73] v0.1.0
+     2 files changed, 29 insertions(+), 31 deletions(-)
+     rewrite config/pkgr.yml (82%)
+     create mode 100755 debian/changelog
+
+Make sure you do not have any staged change (otherwise, commit them):
+
+    $ git status
+    # On branch master
+    nothing to commit (working directory clean)
+
+Finally, ask to build the package on a machine running Debian Squeeze (I generally use my SSH config file to handle the SSH connection details for the specified host):
+
+    $ HOST=debian-build-machine rake pkgr:build:deb
+
+After some time, you should get a final line with the name of your debian package:
+
+    [... lots of lines ...]
+    my-app_0.1.0-1_amd64.deb
+
+Make sure it is really here:
+
+    $ ls -l pkg/
+    total 12128
+    -rw-r--r--  1 crohr  staff  6207392 May  4 10:57 my-app_0.1.0-1_amd64.deb
+
+### Use it
+
+Now you can either upload it to an apt repository (if you have one, I'll make a tutorial on how to set up a simple one), or just test that the package works by installing it on your build machine (or another one, for that matter, but you'll have to manually re-install the dependencies):
+
+    $ scp pkg/my-app_0.1.0-1_amd64.deb debian-build-machine:/tmp/
+    $ ssh debian-build-machine
+    debian-build-machine $ sudo dpkg -i /tmp/my-app_0.1.0-1_amd64.deb
+    Selecting previously deselected package my-app.
+    (Reading database ... 53073 files and directories currently installed.)
+    Unpacking my-app (from /tmp/my-app_0.1.0-1_amd64.deb) ...
+    Setting up my-app (0.1.0-1) ...
+    Installing new version of config file /etc/my-app/pkgr.yml ...
+    Adding system user `my-app' (UID 105) ...
+    Adding new group `my-app' (GID 108) ...
+    Adding new user `my-app' (UID 105) with group `my-app' ...
+    Not creating home directory `/home/my-app'.
+    Starting my-app: OK.
+
+Make sure your app is running:
+
+    debian-build-machine $ ps aux | grep my-app | grep -v grep
+    my-app   13928  3.5 10.5 143436 40004 ?        Sl   11:06   0:02 thin server (0.0.0.0:8000) [my-app-0.1.0]
+
+Notice how the process name shows the version number? From experience, this is really useful.
+
+Now you can send a first request:
+
+    $ curl localhost:8000/
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>The page you were looking for doesn't exist (404)</title>
+      <style type="text/css">
+        body { background-color: #fff; color: #666; text-align: center; font-family: arial, sans-serif; }
+        div.dialog {
+          width: 25em;
+          padding: 0 4em;
+          margin: 4em auto 0 auto;
+          border: 1px solid #ccc;
+          border-right-color: #999;
+          border-bottom-color: #999;
+        }
+        h1 { font-size: 100%; color: #f00; line-height: 1.5em; }
+      </style>
+    </head>
+
+    <body>
+      <!-- This file lives in public/404.html -->
+      <div class="dialog">
+        <h1>The page you were looking for doesn't exist.</h1>
+        <p>You may have mistyped the address or the page may have moved.</p>
+      </div>
+    </body>
+    </html>
+
+Obviously this app does nothing, so you'll get a 404. So go back to building your app, and then just type `rake pkgr:bump:patch` and `HOST=debian-build-machine rake pkgr:build:deb` to generate a new package !
+
+## Release it (debian)
+
+As of 0.2.0, you can now release the latest package on a server, and add it to
+your list of APT sources for easy installation. In the following we'll assume
+that you want to serve your packages from a host called `apt-server`.
+
+Once you've built the package, run the following to upload it to the
+apt-server and generate the manifest:
+
+    $ HOST=apt-server rake pkgr:release:deb
+
+Note that you need **sudo** privileges for this. If all goes well, you should
+now have a directory named `/var/www/my-app` on `apt-server`. The next step is
+to serve this directory over HTTP. Simply enough, install `apache2` and you're
+good to go:
+
+    $ ssh apt-server 'sudo apt-get install apache2 -y'
+
+Now, on the server on which you want to install the package (let's say
+`production-server`), just add an additional APT source file referencing this
+new APT server:
+
+    
+    production-server # cat /etc/apt/sources.list.d/my-app.list
+    deb http://apt-server.ltd/my-app /
+
+And then:
+
+    production-server # apt-get update && apt-get install my-app
+
+Note that you may need to add the following to a
+`/etc/apt/apt.conf.d/allow-unauthenticated` file if apt complains about
+unauthenticated packages:
+
+    production-server # echo 'APT::Get::AllowUnauthenticated "true";' >> /etc/apt/apt.conf.d/allow-unauthenticated
+
+Easy.
+
+## Notes of interest
+
+* your configuration files will be stored in `/etc/my-app/*.yml`, making it easy to manage with Puppet or manually (don't forget to `/etc/init.d/my-app restart` after making changes).
+
+* you can change how the Thin server is launched by adding options to the `/etc/default/my-app` file.
+
+* your log files will be stored in `/var/log/my-app/`.
+
+* your db files will be stored in `var/db/my-app/`.
+
+* if you've got migrations to run, just do a `my-app rake db:migrate` (we might want to run them automatically as part of the postinstall process).
+
+* you can launch a console using `my-app console`.
+
+* use the initd script to start and stop the app: `/etc/init.d/my-app [start|stop|status]`.
+
+## General usage
 
 Declare `pkgr` as one of your **development** dependencies in your `Gemfile`:
 
-    group :development do
-      gem 'pkgr'
-    end
+    gem 'pkgr', :group => :development
+
+Also add `thin`:
+
+    gem 'thin'
 
 Now make sure you have all the gems installed:
 
@@ -80,24 +338,20 @@ Now you can generate all the files required for building a debian package:
 A new directory `debian/` should have been created. You can have a look at it,
 but you should not have to edit anything manually.
 
-Once you're ready to package your app, just run the following steps:
-
-* Increment the version number:
-
-        rake pkgr:bump:patch # or rake pkgr:bump:minor or rake pkgr:bump:major
-
-* Re-generate the debian files:
-
-        rake pkgr:generate
+Once you're ready to package your app, just run the following commands:
 
 * Commit your changes (the `pkgr` app will `git archive HEAD`, which means all
   your changes must be committed first -- we may want to change this):
 
         commit -am "..."
 
+* Increment the version number:
+
+        rake pkgr:bump:patch # or rake pkgr:bump:minor or rake pkgr:bump:major
+
 * Build the package on your machine (default, but you better be running a
-  Debian Squeeze), or on a remote machine (recommended, for instance you can
-  get a Vagrant VM in no time):
+  Debian Squeeze, and have an SSH server running), or on a remote machine
+  (recommended, for instance you can get a Vagrant VM in no time):
 
         HOST=debian-build-machine rake pkgr:build:deb
         # or HOST=localhost rake pkgr:build:deb, or just rake pkgr:build:deb
@@ -105,7 +359,7 @@ Once you're ready to package your app, just run the following steps:
   Note that the user with which you're connecting to the build machine **must
   have `sudo` privileges** (required to install build and runtime
   dependencies).
-
+  
   Also, it's most likely that you'll have to do this a few times at first, as
   well as adding missing runtime and build dependencies, before your app can
   be successfully packaged.
@@ -114,22 +368,8 @@ Once you're ready to package your app, just run the following steps:
   app. Next step is probably to upload it to a local apt repository, and then
   a simple `apt-get install my-app` will install everything. Enjoy!
 
-Have a look at the Getting Started guide in the `doc` folder of this repository.
-
-## Requirements
-
-* You must use Rails3+ and ruby1.9+ in your application. This may work with
-  other rubies but then you'll need to add a rubygems dependency.
-
-* Your Rails application must be able to run with the
-  [`thin`](http://code.macournoyer.com/thin/) web server. Don't forget to add
-  `thin` to your Gemfile!
-
-* Your application must be checked into a **Git** repository. Your name and
-  email is taken from the git configuration, and the changelog is populated
-  based on the git log between two versions.
 
-## TODO
+## Todo
 
 * Speed up the packaging process (currently, bundler re-downloads all the gems
   each time you package an app).

data/lib/pkgr/app.rb

@@ -197,25 +197,18 @@ module Pkgr
       puts "Building debian package on '#{host}'..."
       Dir.chdir(root) do
         Pkgr.mkdir("pkg")
-        case host
-        when 'localhost'
-          debian_steps.each do |step|
-            sh step
-          end
-        else
-          archive = "#{name}-#{version}"
-          sh "scp #{File.expand_path("../data/config/pre_boot.rb", __FILE__)} #{host}:/tmp/"
-          cmd = %Q{
-            git archive #{git_ref} --prefix=#{archive}/ | ssh #{host} 'cat - > /tmp/#{archive}.tar &&
-              set -x && rm -rf /tmp/#{archive} &&
-              cd /tmp && tar xf #{archive}.tar && cd #{archive} &&
-              cat config/boot.rb >> /tmp/pre_boot.rb && cp -f /tmp/pre_boot.rb config/boot.rb &&
-              #{debian_steps.join(" &&\n")}'
-          }
-          sh cmd
-          # Fetch the .deb, and put it in the `pkg` directory
-          sh "scp #{host}:/tmp/#{name}_#{version}*.deb pkg/"
-        end
+        archive = "#{name}-#{version}"
+        sh "scp #{File.expand_path("../data/config/pre_boot.rb", __FILE__)} #{host}:/tmp/"
+        cmd = %Q{
+          git archive #{git_ref} --prefix=#{archive}/ | ssh #{host} 'cat - > /tmp/#{archive}.tar &&
+            set -x && rm -rf /tmp/#{archive} &&
+            cd /tmp && tar xf #{archive}.tar && cd #{archive} &&
+            cat config/boot.rb >> /tmp/pre_boot.rb && cp -f /tmp/pre_boot.rb config/boot.rb &&
+            #{debian_steps.join(" &&\n")}'
+        }
+        sh cmd
+        # Fetch the .deb, and put it in the `pkg` directory
+        sh "scp #{host}:/tmp/#{name}_#{version}*.deb pkg/"
       end
     end
 
@@ -231,6 +224,23 @@ module Pkgr
         "dpkg-buildpackage -us -uc -d"
       ]
     end
+    
+    def release_debian_package(host, apt_directory = nil)
+      apt_directory ||= "/var/www/#{name}"
+      latest = Dir[File.join(root, "pkg", "*.deb")].find{|file| file =~ /#{version}/}
+      raise "No .deb available in pkg/" if latest.nil?
+      latest_name = File.basename(latest)
+      sh "scp #{latest} #{host}:/tmp/"
+      sh "ssh #{host} 'sudo mkdir -p #{apt_directory} && sudo chown $USER #{apt_directory} && mv /tmp/#{latest_name} #{apt_directory} && cd #{apt_directory} && ( which dpkg-scanpackages || sudo apt-get update && sudo apt-get install dpkg-dev -y ) && dpkg-scanpackages . | gzip -f9 > Packages.gz'"
+      puts "****"
+      puts "Now you just need to serve the '#{apt_directory}' directory over HTTP, and add a new source to your APT configuration on the production server:"
+      puts "$ cat /etc/apt/sources.list.d/#{name}.list"
+      puts "deb http://apt-server.ltd/#{name} /"
+      puts
+      puts "And then:"
+      puts "$ sudo apt-get update && sudo apt-get install #{name}"
+      puts "****"
+    end
 
     private
     def bundler_version

data/lib/pkgr/pkgr.rake

@@ -38,5 +38,13 @@ namespace :pkgr do
         APP.build_debian_package(build_host)
       end
     end
+    
+    namespace :release do
+      desc "Release the latest package on a custom APT repository"
+      task :deb do
+        apt_host = ENV.fetch('HOST') { 'localhost' }
+        APP.release_debian_package(apt_host)
+      end
+    end
   end
 end

data/lib/pkgr/version.rb

@@ -1,3 +1,3 @@
 module Pkgr
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pkgr
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors: