Deploying Yesod applications with Keter
Keter is the Yesod’s deployment system, fully featured and a joy to use, but there are some pitfalls that the documentation doesn’t cover, and that the user has to find out for her self; So I’ll try to give them away here together with a walk-through tutorial.
Although Keter is flexible and general enough to be used with various kind of applications and web frameworks, here I’m going to assume you’re using it to deploy Yesod applications. Moreover, I’ll assume you’re using Yesod’s scaffolding, as it is the preferred way to write production ready applications.
I’m also taking for granted that you’ve already installed on your server system whatever DBMS that your Yesod app needs, and have also created the app’s databases.
Installing Keter on the server
Keter binary
It is always advisable to compile on the development machine rather than the production server, to avoid utilising its resources for building (specially considering that GHC can make use of a fair amount of them). So, assuming the architectures match, you can just install keter on you local machine:
$ stack install keter
And then put the binary on the server (example.com):
$ scp ~/.local/bin/keter root@example.com:/root/
Keter user
It’s a good practice to have a dedicated keter user, so you don’t have to deploy as root each time:
# useradd keter
# passwd keter
Directory tree
The directory tree needed on the server is as follows:
keter
├── bin
│ └── keter
├── etc
│ └── keter-config.yaml
├── incoming
└── app.keter
So create it, copy the binary to /opt/keter/bin, and make sure /opt/keter/incoming it’s owned by the keter user (we’ll take care of the keter-config.yaml configuration later):
# mkdir -p /opt/keter /opt/keter/bin /opt/keter/etc /opt/keter/incoming
# cp /root/keter /opt/keter/bin
# touch /opt/keter/keter-config.yaml
# chown -R keter:keter /opt/keter/icoming
Init System
While you could just execute /opt/keter/bin/keter directly, it’s better to register it as a job in your Init System.
Sysmted (RedHat, Fedora, CentOS, Arch, openSUSE, etc)
Create a file /etc/systemd/system/keter.service, with the contents:
[Unit]
Description=Keter
After=network.service
[Service]
Type=simple
ExecStart=/opt/keter/bin/keter /opt/keter/etc/keter-config.yaml
[Install]
WantedBy=multi-user.target
Enable the service:
$ sudo systemctl enable keter
Now you can start keter with (don’t do it just yet, as we still need to write the keter configuration file):
$ sudo systemctl start keter
Upstart (Debian, Ubuntu, etc)
Create a file /etc/init/keter.con, with the contents:
start on (net-device-up and local-filesystems and runlevel [2345])
stop on runlevel [016]
respawn
console output
exec /opt/keter/bin/keter /opt/keter/etc/keter-config.yaml
Now you can start keter with (don’t do it just yet, as we still need to write the keter configuration file):
$ sudo start keter
Configuration
Server Side
The Keter configuration at /opt/keter/etc/keter-config.yaml is pretty straight forward:
root: ..
listeners:
# HTTP
- host: "*4" # Listen on all IPv4 hosts
port: 80
# HTTPS
#- host: "*4"
#port: 443
#key: key.pem
#certificate: certificate.pem
# env:
# key: value
The root option points, as expected, to /opt/keter.
Make sure to change the port option if you’re reverse forwarding from a fronted server like Nginx or Apache (more on this later).
If you’re serving your application over SSL (and you should), uncomment the HTTPS section, then point the key option to your privkey.pem file, and the certificate option to your fullchain.pem file.
The env option, keeps pairs of keys and values. The main set of values you’ll need here are your Database credentials. You’ve probably already configured database credentials in the database section in the config/settings.yaml file, so you’ll notice you need some environment variables like MYSQL_USER, MYSQL_PASSWORD, etc. If you’re using MySQL/MariaDB; Or PGUSER, PGPASS, etc. If you’re using PostgreSQL. You get the idea.
This is how it will look like for a PostgreSQL Database where only the user and password are different between the development and production servers (be sure to keep the quotes).
env:
PGUSER: "user"
PGPASS: "password"
Yesod application side
The Keter configuration file for your Yesod application lives in config/keter.yml. Set user-edited to true, so you’re able to execute yesod keter later on.
Locate the copy-to option and configure it to use the keter user and your server domain (or IP address):
copy-to: keter@example.com:/opt/keter/incoming/
This will allow you to deploy your application with:
$ stack -- exec yesod keter
Hosts Configuration
The most important part of the Keter configuration is perhaps the hosts option of the webapp stanza, the hosts you declare here are the ones that your application is going to respond to. Unless you’re using a separate domain for serving static files, be sure to keep the hosts option of the static-files stanza in sync with the webapp one.
This one here is a pretty common error message when trying to deploy a Yesod application (and failing miserably):
There is more than one reason for this, but the main one is that the domain name or IP address doesn’t exactly match one of the hosts provided in the hosts option.
If you’re serving only one application and using Keter as the main server listening on port 80, then having your domain name in hosts will pretty much suffice, BUT most of the time, even if your serving only one application, you’re probably using a frontend server like Nginx or Apache, in which case you have to consider the port the reverse proxy is pointing to.
Take for instance this Nginx reverse proxy configuration for an app that lives on blog.example.com
server {
listen 80;
server_name blog.example.com;
location / {
proxy_pass http://127.0.0.1:4321;
}
With a Keter configuration that has:
listeners:
- host: "*4" # Listen on all IPv4 hosts
port: 4321
Then you have a problem. If you try to connect to http://blog.example.com you’ll get the aforementioned error message, telling you that “127.0.0.1:4321, is not recognized”. It makes sense if you think about it, Nginx will redirect the connection to 127.0.0.1:4321 so Keter can handle it, but there is no application that responds to 127.0.0.1:4321, and notice the port number here, as it is significant for Keter when trying to find a corresponding application.
To fix this, we must allow our application to respond to 127.0.0.1:4321 as well:
hosts:
- blog.example.com
- blog.example.com:4321
- 127.0.0.1:4321
Restart Ngnix and Keter on the server to allow the configuration to take effect and redeploy the application:
$ stack -- exec yesod keter
Redirections
If you’re going to use the redirect stanza to automatically redirect any connection to, lets say example.com to wwww.example.com:
- type: redirect
hosts:
- example.com
actions:
- host: www.example.com
Then be completely sure to have www.example.com in the hosts option of the webapp stanza as well, failing to do this will take you to the same error message.
Other sources of error
“Welcome to Keter”
If you’re still reaching this error:
Unfortunately, the same error message appears if an application that responds to that host is actually found, but is failing to start.
Check the /opt/keter/log/app-yourapp/current.log log file, chances are you have changes in your persistent models that can’t be reflected in your database without user intervention, so be sure to manually fix them the same way you have to do in your development database.
Changes in new deployed version not taking effect
It is pretty common to forget changes in persistent models that need manual user intervention after deploying, similarly to the error above, this will prevent the app to start. If you currently have a version of your app working, Keter will use it instead of the new one if it fails to start, so if the latest deployed changes seem to not be taking effect, this can also be the source of the problem.
Keter is the Yesod’s deployment system, fully featured and a joy to use, but there are some pitfalls that the documentation doesn’t cover, and that the user has to find out for her self; So I’ll try to give them away here together with a walk-through tutorial.
Although Keter is flexible and general enough to be used with various kind of applications and web frameworks, here I’m going to assume you’re using it to deploy Yesod applications. Moreover, I’ll assume you’re using Yesod’s scaffolding, as it is the preferred way to write production ready applications.
I’m also taking for granted that you’ve already installed on your server system whatever DBMS that your Yesod app needs, and have also created the app’s databases.
Installing Keter on the server
Keter binary
It is always advisable to compile on the development machine rather than the production server, to avoid utilising its resources for building (specially considering that GHC can make use of a fair amount of them). So, assuming the architectures match, you can just install keter on you local machine:
$ stack install keterAnd then put the binary on the server (example.com):
$ scp ~/.local/bin/keter root@example.com:/root/Keter user
It’s a good practice to have a dedicated keter user, so you don’t have to deploy as root each time:
# useradd keter
# passwd keterDirectory tree
The directory tree needed on the server is as follows:
keter
├── bin
│ └── keter
├── etc
│ └── keter-config.yaml
├── incoming
└── app.keterSo create it, copy the binary to /opt/keter/bin, and make sure /opt/keter/incoming it’s owned by the keter user (we’ll take care of the keter-config.yaml configuration later):
# mkdir -p /opt/keter /opt/keter/bin /opt/keter/etc /opt/keter/incoming
# cp /root/keter /opt/keter/bin
# touch /opt/keter/keter-config.yaml
# chown -R keter:keter /opt/keter/icomingInit System
While you could just execute /opt/keter/bin/keter directly, it’s better to register it as a job in your Init System.
Sysmted (RedHat, Fedora, CentOS, Arch, openSUSE, etc)
Create a file /etc/systemd/system/keter.service, with the contents:
[Unit]
Description=Keter
After=network.service
[Service]
Type=simple
ExecStart=/opt/keter/bin/keter /opt/keter/etc/keter-config.yaml
[Install]
WantedBy=multi-user.targetEnable the service:
$ sudo systemctl enable keterNow you can start keter with (don’t do it just yet, as we still need to write the keter configuration file):
$ sudo systemctl start keterUpstart (Debian, Ubuntu, etc)
Create a file /etc/init/keter.con, with the contents:
start on (net-device-up and local-filesystems and runlevel [2345])
stop on runlevel [016]
respawn
console output
exec /opt/keter/bin/keter /opt/keter/etc/keter-config.yamlNow you can start keter with (don’t do it just yet, as we still need to write the keter configuration file):
$ sudo start keterConfiguration
Server Side
The Keter configuration at /opt/keter/etc/keter-config.yaml is pretty straight forward:
root: ..
listeners:
# HTTP
- host: "*4" # Listen on all IPv4 hosts
port: 80
# HTTPS
#- host: "*4"
#port: 443
#key: key.pem
#certificate: certificate.pem
# env:
# key: valueThe root option points, as expected, to /opt/keter.
Make sure to change the port option if you’re reverse forwarding from a fronted server like Nginx or Apache (more on this later).
If you’re serving your application over SSL (and you should), uncomment the HTTPS section, then point the key option to your privkey.pem file, and the certificate option to your fullchain.pem file.
The env option, keeps pairs of keys and values. The main set of values you’ll need here are your Database credentials. You’ve probably already configured database credentials in the database section in the config/settings.yaml file, so you’ll notice you need some environment variables like MYSQL_USER, MYSQL_PASSWORD, etc. If you’re using MySQL/MariaDB; Or PGUSER, PGPASS, etc. If you’re using PostgreSQL. You get the idea.
This is how it will look like for a PostgreSQL Database where only the user and password are different between the development and production servers (be sure to keep the quotes).
env:
PGUSER: "user"
PGPASS: "password"Yesod application side
The Keter configuration file for your Yesod application lives in config/keter.yml. Set user-edited to true, so you’re able to execute yesod keter later on.
Locate the copy-to option and configure it to use the keter user and your server domain (or IP address):
copy-to: keter@example.com:/opt/keter/incoming/This will allow you to deploy your application with:
$ stack -- exec yesod keterHosts Configuration
The most important part of the Keter configuration is perhaps the hosts option of the webapp stanza, the hosts you declare here are the ones that your application is going to respond to. Unless you’re using a separate domain for serving static files, be sure to keep the hosts option of the static-files stanza in sync with the webapp one.
This one here is a pretty common error message when trying to deploy a Yesod application (and failing miserably):
There is more than one reason for this, but the main one is that the domain name or IP address doesn’t exactly match one of the hosts provided in the hosts option.
If you’re serving only one application and using Keter as the main server listening on port 80, then having your domain name in hosts will pretty much suffice, BUT most of the time, even if your serving only one application, you’re probably using a frontend server like Nginx or Apache, in which case you have to consider the port the reverse proxy is pointing to.
Take for instance this Nginx reverse proxy configuration for an app that lives on blog.example.com
server {
listen 80;
server_name blog.example.com;
location / {
proxy_pass http://127.0.0.1:4321;
}With a Keter configuration that has:
listeners:
- host: "*4" # Listen on all IPv4 hosts
port: 4321Then you have a problem. If you try to connect to http://blog.example.com you’ll get the aforementioned error message, telling you that “127.0.0.1:4321, is not recognized”. It makes sense if you think about it, Nginx will redirect the connection to 127.0.0.1:4321 so Keter can handle it, but there is no application that responds to 127.0.0.1:4321, and notice the port number here, as it is significant for Keter when trying to find a corresponding application.
To fix this, we must allow our application to respond to 127.0.0.1:4321 as well:
hosts:
- blog.example.com
- blog.example.com:4321
- 127.0.0.1:4321Restart Ngnix and Keter on the server to allow the configuration to take effect and redeploy the application:
$ stack -- exec yesod keterRedirections
If you’re going to use the redirect stanza to automatically redirect any connection to, lets say example.com to wwww.example.com:
- type: redirect
hosts:
- example.com
actions:
- host: www.example.comThen be completely sure to have www.example.com in the hosts option of the webapp stanza as well, failing to do this will take you to the same error message.
Other sources of error
“Welcome to Keter”
If you’re still reaching this error:
Unfortunately, the same error message appears if an application that responds to that host is actually found, but is failing to start.
Check the /opt/keter/log/app-yourapp/current.log log file, chances are you have changes in your persistent models that can’t be reflected in your database without user intervention, so be sure to manually fix them the same way you have to do in your development database.
Changes in new deployed version not taking effect
It is pretty common to forget changes in persistent models that need manual user intervention after deploying, similarly to the error above, this will prevent the app to start. If you currently have a version of your app working, Keter will use it instead of the new one if it fails to start, so if the latest deployed changes seem to not be taking effect, this can also be the source of the problem.