Uberspace

Description

Uberspace is a shared webhosting service in Germany, giving you huge flexibility in administration. You can also install Mojolicious running hypnotoad with just a few steps.

This tutorial describes running Mojolicious on Uberspace 5, which is now deprecated. For Uberspace >= 6 it is recommended to use perlbrew + cpanm to install. Uberspace 7 uses supervisord instead of demontools to run services.

Check for your Perl version

First you should log in to your uberspace via ssh from your local console, e.g.

> ssh {username}@{servername}.uberspace.de

In your homefolder just check the version of your Perl installation - remember: Mojolicious needs at least Perl v5.10.1!

> perl -v

Maybe you are lucky and you are on a machine with at least Perl v5.10.1. Then you can forward to step "Update your CPAN" of this recipe. If your luck is out for lunch: Updating your Perl is easy. You can check for the most recent version of perl available using

> toast find perl

Then get the latest version installed (v5.16 in this case):

> toast arm perl/5.16.0

After it's built (this can take quite a while), you should log out and log in again and check, if it works.

> perl -v

If you still see your old perl coming up, check if there's a perl5.16.0 or somehing in your path. Maybe it will help to set an alias for perl in your .bashrc: alias perl="..." Now your perl should be hot. If it still can't be found you have to make some shebang fun like "#!/home/{username}/.toast/armed/bin/perl5.16.0" ... whatever. Shouldn't be complicated.

Update your CPAN

Now start cpan.

> cpan

It will ask you, if you want to configrue everything manually or not ... well, you'll be fine with the default stuff, so just press "enter". Then you should automatically be forced to install your libraries via "local::lib" - so everything you do will be installed locally. That's cool. Say "yes" to everything until you are in the cpan prompt.

Alternatively you can adjust the settings in your local cpan configuration file that is located at ~/.cpan/CPAN/MyConfig.pm. All cpan settings are saved as a key-value pair in the hash reference $CPAN::Config in that file. The two crucial keys are makepl_arg and mbuildpl_arg. They contain the arguments that are passed to perl Make.PL respectively perl Build.PL (for more information see the Config Variables section in the cpan documentation). For me it works with the following set-up:

'makepl_arg' => q[INSTALLDIRS=perl INSTALLBIN=~/bin/ INSTALLARCHLIB=~/perl5/ INSTALLPRIVLIB=~/perl5/ INSTALLSCRIPT=~/perl5/ INSTALLMAN1DIR=~/man/ INSTALLMAN3DIR=~/man/],
'mbuildpl_arg' => q[--install_path lib=~/perl5/ --install_path arch=~/perl5/ --install_path script=~/bin/ --install_path bindoc=~/man/ --install_path libdoc=~/man/],

of course the directories ~/man, ~/perl5 and ~/bin must exist. In order that perl find the installed modules i recommend to add the line

export PERL5LIB=~/perl5

to your ~/.bashrc.

Now upgrade ...

cpan[1]> upgrade

... and wait or do some Mojo fun meanwhile or look out of the window - there may be a rainbow! Or two!

Install Mojolicious

Now install Mojolicious to your local cpan.

cpan[1]> install Mojolicious

This will be quite quick. The next mojo magic will now be available for everyone on your Uberspace! Leave cpan for the moment

> exit

Create your first Mojolicious::Lite app

First you should create an app folder below your homedirectory and generate a Mojolicious::Lite app.

> mkdir app
> cd app
app> mojo generate lite_app
app> cd ..

Test your app using hypnotoad

> hypnotoad -t app/myapp

Everything works fine? Great.

Bring your app to the web

Now that hypnotoad principally works, you have to modify your app to make hypnotoad listen to a special port. Edit your app with

> emacs app/myapp

(...or any installed editor you like better ...) and add the following line to your mojo app (e.g. after "use Mojolicious::Lite;").

app->config(hypnotoad => {listen => ['http://*:8765']});

Do not use exactly 8765 - any high free port on this server is fine! If you are using Mojolicious::Plugin::Config, just put this line anywhere in your config file. Exit the editor (for Emacs with Ctrl-x Ctrl-C) and start hypnotoad:

> hypnotoad app/myapp

Fine. Now you have to make apache know where your hypnotoad is: just add a rewrite rule to your .htaccess.

> emacs html/.htaccess

RewriteEngine On
RewriteRule ^(.*) http://127.0.0.1:8765/$1 [p]

(Just add more rules, for example for your public folder etc.)

Okay ... hypnotoad is running, the rewrite rules are set - check if everything works as expected! Open your browser and go to your uberspace:

https://{username}.{servername}.uberspace.de/

Does it work? Great! (If it doesn't, maybe you have to change the shebang of your app to find your perl version or something.)

Everything is fine ... or ... wait a minute? What happens, if the process dies or the guys from Uberspace stumble upon a cable??!

First stop your hypnotoad:

> hypnotoad -s app/myapp

Configure Daemon Tools

Uberspace uses daemon tools to set up your hypnotoad as a service process that will be controlled and restarted automatically. To the best of my knowledge, this will unfortunately mean: No hot deployment anymore, because if the daemon is restarted, the workers won't die gracefully ... whatever.

First create your personal service directory:

> uberspace-setup-svscan

This will create a service directory in your home folder. Now create a service for your app:

> uberspace-setup-service myapp hypnotoad -f ~/app/myapp

Hypnotoad has to run in foreground (-f switch) so the daemon watcher knows it's still alive. That's why hot deployment isn't enabled.

Changing your app

Now whenever you update your app, you can't just restart hypnotoad, you have to restart the service. For this just type in

> svc -h ~/service/myapp

and your app will be restarted!

Some pitfalls

Uberspace is pretty well configured for proxy access, but you may have to change your program code to work with helpers like url_for. Just add the following lines to your app, so url_for knows, where your app is located externally.

app->hook(
  before_dispatch => sub {
    my $c = shift;
    my $req = $c->req;
    my $h = $req->headers;
    if ($h->header('X-Forwarded-Host')) {
      for ($req->url->base) {
        $_->host(scalar $h->header('X-Forwarded-Host'));
        $_->port(scalar $h->header('X-Forwarded-Port') || 80);
      };
    };
  });

And ... ?

Now have fun with Mojolicious and discover the possibilities of your Uberspace, using MongoDB, CouchDB ... even websockets are possible, if you ask the administrators to open the port for it. More information can be found on the Uberspace Wiki (in german).