ShrimpWorks

Yup. It looks different. For the first time in over 11 years, this website is not being built dynamically by PHP scripts.

I’ve jumped on the static site generation bandwagon, and after taking a look at several options (primarily Hugo and Nikola), and decided to settle on Jekyll. At the end of the day the easiest to install and get started with won, basically (which I found amusing for a Ruby project, for some reason).

There are a couple of reasons for wanting to change. Primarily, it seems every second day I read about some new Wordpress exploit wiping out sites left right and centre. It’s just another point of admin to update things all the time, which I could do without. Additionally, I’m tired of bots smashing into the admin login page all day. While it doesn’t really impact me all that much, it’s just something that bothers me.

The myriad plugins “required” to manage comment spam, the aforementioned login attempts, galleries, links, etc. all provide their own potential security issues, and all need to be regularly updated (assuming their authors didn’t abandon them years ago).

Finally, I wanted to do some custom design (yes, I’m not fantastic at it), but the thought of building mixed HTML and PHP templates for Wordpress horrifies me.

For the conversion, I used the Jekyll Wordpress migration process, which resulted in a bit of a mess, followed by conversion from HTML to Markdown using Pandoc, which did an excellent job. Over several days I had to clean up and reformat most pages, rebuild the galleries, redesign everything, etc., but I feel the result is worth it.

The full source code (plugins, config, assets, posts etc) are available in GitHub if anyone wants to steal anything.

Now that we have dependency management with Ivy working along with everything else covered before, we’ve covered almost everything required to start building real projects with Ant.

Another thing any real project should have, is unit tests. Thankfully, using the scaffolding already put in place in earlier parts of this series, integrating a JUnit testing task into our existing build script is really straight-forward.

Continue Reading ...

So far, we’ve covered the basics of creating a re-distributable .jar package suitable for use as a library, and building a Jar file which can be run by a user or server process.

A major part of any non-trivial application these days is the inclusion and re-use of 3rd party libraries which implement functionality your applications require. When a project starts, it’s probably easy enough to manually drop the odd jar library into a lib directory and forget about it, but maintaining a large application which depends on many libraries, which in turn depend on additional libraries for their own functionality, it can quickly turn into a nightmare to manage.

To solve this problem, many dependency management tools have been introduced, most notably, Apache Maven. Maven however, is so much more than just a dependency management tool, and is actually intended to manage your entire project structure. I believe however, the combination of Ant and Ivy provides far more flexibility, extensibility and control over your build and dependency management processes.

So, let’s integrate Apache Ivy into our Ant script as we left it in part 2.

Continue Reading ...

In part 1, we went over the basics of using Ant to create a redistributable .jar file, suitable for use as a library in other projects. A lot of the time however, you’re probably going to want to be building things which can actually be run as regular Java applications.

Once again, the code for this tutorial is available in GitHub. More usefully, you may want to see the diff between the part 1 script and the new one.

Here’s a quick explanation of what we’ve done to achieve an executable jar file:

Continue Reading ...

Apache Ant is a general-purpose build tool, primarily used for the building of Java applications, but it is flexible enough to be used for various tasks.

In the Java world at least, Ant seems to be largely passed over for the immediate convenience and IDE support of Maven, however long term, I believe a good set of Ant scripts offer far more flexibility and room for tweaking your build processes. The downside is that there’s a lot of stuff you need to learn and figure out and build by hand.

In this series of tutorials, I’ll try to document the process of learning I’ve gone through building and maintaining Ant build files, from the most basic of “just compile my stuff” steps to automatic generation of JavaDoc output, dependency management using Ant’s companion, Ivy, unit testing using JUnit, and integrating with some additional tools I’ve been using, such as Checkstyle and FindBugs.

For part 1 of this tutorial, I’ve created a simple Hello World library. It doesn’t have a main executable itself, the goal of this is to produce a .jar file we can include in other projects, to start our Ant script off fairly simply.

The source for this project can be found in GitHub. Here’s the breakdown of everything going on in this project:

Continue Reading ...

I’ve been meaning to do some posts on setting up a Java build process using Apache’s Ant and Ivy, but never really get that far.

I’m a fan of allowing build dependencies (beyond the actual Ant binary itself) download automagically as part of the build, rather than requiring the developer to download and install a bunch of different tools and then orchestrating them via Ant. Essentially you should be able to install Ant, grab the code of something you want to build, and execute it.

To this end I have spend many hours trying to get the FindBugs static analysis tool and it’s requirements downloaded as Ivy dependencies as is possible with most tools, but gave up due to some rather weird and seemingly hard-coded dependency paths and file names within the FindBugs project.

Therefore I gave up and just have it downloading using an Ant “get” task, which feels a bit brute-force, but sometimes you need to compromise. Here’s my solution, presented as an all-in-one Ant target:

Continue Reading ...

While it amounts to little more than a Markdown renderer in this case (with only a single, relatively small document on show), using GitHub pages and a simple branch from master, you can now see Markdocs in action.

Here’s a thing I’ve been wanting for a while now, and have been unable to something to suite my needs (well, more wants than needs, I guess). I end up generating a lot of text/documentation for various things (both at home and work), normally spread around a little - project descriptions and introductions in READMEs, APIs and design plans in wikis, sometimes random files, etc, and wanted the ability to consolidate these into collections that could be nicely presented, either publicly or for team reference.

My preferred requirements, which were not met by existing solutions such as Sphinx, Read the Docs, Beautiful docs and Daux.io are:

• No need to pre/post processing the input documents as a separate “compile” or parsing step
  • Should use existing plain Markdown documents as input and format output at runtime only
• Along with the above, the documents should be “live” - if I change the source file, I don’t want to “recompile” my documentation pages, they should reflect changes by default
• Not a hosted solution
  • Particularly, something anyone can drop on a private server (work environment) or whatever they want to do with it
• No server-side requirements beyond simple HTTP file serving
• I may be out of the JavaScript development scene, but what’s up with requiring users to use a dozen different build systems and dependency management frameworks to use your JavaScript app these days?
  • Seriously, the attraction used to be that you could simply drop a couple of HTML, CSS and JS files in your www-root and magic came out. Get off my lawn!

My solution is Markdocs - a simple HTML and JavaScript application for organising individual Markdown documents as a documentation collection.

See the README on the Markdocs GitHub page for usage instructions. Basically, you define the documents to include via a simple JSON file, which is loaded at runtime. The required documents are then loaded using jQuery, parsed at runtime with Marked right in the user’s browser, and a table of contents and the documents themselves are generated and presented using a simple Semantic UI interface.

At present it’s perfectly usable, but there are still a couple of things I want to improve and add, including suitable inter-document linking (while not enforcing any magic link syntax - your stand-alone document should still work as stand-alone documents) and ability to provide links to the individual source documents as well as an “Edit” link (for example, let you define a link to the editable document on GitHub).

Will update as it progresses.

I’ve become fond of using nginx on my development machines, rather than a full Apache.

There are no explicit options built-in which allow something along the same lines as Apache’s userdir, however it’s easy enough to tweak the default configuration to support that behaviour without the need for external modules.

I also do some PHP dabbling from time to time, so need to enable that as well.

Install the required bits:

$ sudo aptitude install nginx php5-fpm

Configure nginx (the below is my customised and cleaned out server definition):

/etc/nginx/sites-available/default

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;

    # Add index.php to the list if you are using PHP
    index index.html index.htm index.nginx-debian.html index.php;

    server_name _;

    # PHP support in user directories
    location ~ ^/~(.+?)(/.*\.php)$ {
        alias /home/$1/public_html;
        autoindex on;

        include snippets/fastcgi-php.conf;

        try_files $2 = 404;
        fastcgi_pass unix:/var/run/php5-fpm.sock;
    }

    # PHP support in document root
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php5-fpm.sock;
    }

    # User directories in /home/user/public_html/
    # are accessed via http://host/~user/
    location ~ ^/~(.+?)(/.*)?$ {
        alias /home/$1/public_html$2;
        autoindex on;
    }
}

I also had to make a change to /etc/nginx/snippets/fastcgi-php.conf, to comment out the following line:

#try_files $fastcgi_script_name =404;

After restarting the nginx service (also make sure the php5-fpm service is running), you will be able to serve HTML and PHP files from your ~/public_html directory.

Recently, I’ve made the switch from KDE being my preferred Linux desktop environment/window manager, to i3, a tiling window manager, for both my work and private development environments (my home desktop is still Windows 7, since I do still game enough for it to become painful to dual-boot - so I do most of my development within a VM these days).

I really like it’s absolutely minimal approach - essentially it does nothing itself, it provides a simple window manager, and near limitless configurability. This has proven an excellent learning experience for me, since it’s forced me to get a lot closer to system components usually “hidden” behind sliders and widgets in KDE or Gnome, as well as a host of alternatives to applications those environments provide by default. It’s also resulted in a much cleaner and faster system, containing only the applications and services I actually want.

We recently installed fresh new desktop machines at work, so I thought I’d share some of my setup, in case it’s of some value to anyone else (and my own future reference!). The following steps assume you know how to operate a basic Debian system. I’m not going to go too deep into any usage details for i3 either, since there’s an excellent user guide and comprehensive FAQ system which should answer any questions you may have.

I’d also advocate using “aptitude” as an alternative to “apt-get” for all package installations, updates and removals.

The Basics

I always start off with a Debian “netinst”. Post-install, this provides an incredibly basic bare-bones OS with a few system utilities (during the installation, de-select the pre-configured “Desktop”, “Web Server”, “Mail Server”, etc. options, just keep the “Standard System Utilities”).

First thing to to after installing is install sudo and add your user to the sudoers group, to avoid having to be root to get things done. Now’s also a good time to install vim.

I also like seeing Aptitude’s “visual preview” of changes when doing package management, so to avoid having to call $ aptitude --visual-preview install ... on every invocation, we can edit root’s aptitude config:

/root/.aptitude/config:

Aptitude::CmdLine::Visual-Preview "true";

Upgrade to Unstable/Sid

Perhaps a bit reckless, but I’ve honestly never experienced any crippling issues running Debian Unstable (“sid”). You’ll only need to modify /etc/apt/source.list and replace references to “wheezy” or “testing” with “unstable” or “sid”, and disable the updates and security repositories, leaving you only the main deb and deb-src repositories (I’ve enabled non-free and contrib, since I want to install FlashPlayer and nVidia drivers later):

/etc/apt/source.list:

deb http://cdn.debian.net/debian/ unstable main non-free contrib
deb-src http://cdn.debian.net/debian/ unstable main non-free contrib

After saving the above changes, execute the following:

$ sudo aptitude update
$ sudo aptitude dist-upgrade

The dist-upgrade step will upgrade all installed packages to whatever’s newest in unstable.

Desktop Install

With the base system as up-to-date as it can be, it’s time to install the desktop environment.

$ sudo aptitude install xorg lightdm i3-wm i3status suckless-tools

After installation, I’d reboot and ensure a nice graphical login prompt appears. After login, you’ll be asked some initial i3 setup questions (which are easy to change later) and land in the default i3 workspace. Press Mod+Enter (Mod being whatever you selected in the aforementioned setup questions - likely “windows” key, or Ctrl) to open a new terminal window. It’s probably xterm, which is sort of OK, but I switched to lxtermial - it’s nice and lightweight but still has a fair number of configuration and convenience features (like URL detection - useful for IRC).

If you install another terminal, and opening more terminals results in more xterms rather than your installed terminal, do the following to set your preferred option:

$ sudo update-alternatives --config x-terminal-emulator

Desktop Tweaks

Before digging too deep into installing additional software, it’s a good time to configure some additional options to make life a bit more pleasant.

Look and Feel

In order to make sure your eyes are not offended by the default GTK theme which you may end up seeing a lot of, set up the GTK theme and icon theme:

~/.gtkrc-2.0:

include "/usr/share/themes/Adwaita/gtk-2.0/gtkrc"
gtk-icon-theme-name="Adwaita"

In addition, I found it a lot cleaner and space-maximising to disable i3’s window titles and thin it’s borders down, by addition the following to ~/i3/config:

new_window 1pixel
new_float normal

py3status

Install python-pip via Aptitude, and then $ sudo pip install py3status. I use py3status since it provides some nice additional modules, is more flexible, and is fully compatible with the default i3status configuration. It’s also a good time to check out the i3status configuration documentation and do some tweaks, since a couple of the default entries here are likely not too useful.

Wallpaper

Randomised (of fixed if preferred) wallpapers can easily be achieved by installing feh (which makes for a good i3-friendly picture viewer in general) then adding the following to ~/i3/config:

exec --no-startup-id feh --recursive --randomize --bg-fill ~/Pictures/wallpaper/

Incidentally, the imgur wallpaper gallery is a good place to find some wallpapers.

File Management

Sometimes a GUI file manager can be useful, and for this, a nice light-weight alternative to the bigger desktops’ Nautilus and Dolphins is PCManFM, installed as pcmanfm.

A nice companion application for (compressed) archive management is xarchiver. You may need to install additional tools (such as zip, unzip, unrar-free, etc, depending on the files you commonly work with).

Conclusion

The entire setup to this point should not have taken more than 1-2 hours, depending on download speeds (really, most time is spent just waiting for downloads…), so you can get this kind of environment running with minimal effort and downtime.

I haven’t included anything about multimedia, custom key bindings, lock screens, or others here, but there are loads of other resources around which can fill you in on those and the myriad ways you can configure your i3 environment.

Your next step, if you’re new to i3, should probably be to take a read through the i3 user guide, which is impressively comprehensive.