How to deploy a Crystal Lucky application with Dokku on Ubuntu 18.04

2020-05-20T00:00:00+00:00

This tutorial will show how to set up an app written in the Crystal web framework Lucky</a> with Dokku on Ubuntu 18.04.

You can run this setup on most low-end boxes, e.g. a $5 Digital Ocean droplet, or in my case, a $2.50 Hetzner Cloud Server</a>.

By the end of the tutorial you'll know how to deploy your own Lucky apps and be able to manage them easily all on one server.

What is Lucky?</h3>
Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.

What is Dokku?</h3>
Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.

Prequisites</h2>

Crystal 0.34.0 installed locally</li>
A fresh Lucky application installed and running locally.</li>
Basic knowledge of Git.</li>
A server with Dokku Installed</a> using Ubuntu 18.04.</li>
A domain or subdomain to point to the server.</li> </ul>
You'll need a Lucky app to deploy. If you don't have one then no problem! A fresh Lucky app comes with several goodies out of the box, a home page and an authentication system linked to a database. This is more than enough to work with. See Getting Started</a> and Starting a Lucky Project</a>. Make sure you have the project commited to git and ready for the first deployment.
Step 1 - Setting up the Dokku configuration</h2>
SSH into your server to get it ready for deployment.
ssh root@ip </code></pre> In the following commands replace app.example.com</code> with your domain or subdomain. Replace exampledb</code> with your preferred database name. This will create the initial app container in Dokku, create the database, and link them both together. The last three lines set environment variables for the Lucky app. The first will tell Lucky to run the app in production</code> mode, the second will tell Lucky what the app URL is, and the third will tell the app to run on port 5000 which Dokku will connect with Nginx to expose to the world.
dokku apps:create app.example.com dokku postgres:create exampledb dokku postgres:link exampledb app.example.com dokku config:set app.example.com LUCKY_ENV=production dokku config:set app.example.com APP_DOMAIN=app.example.com dokku config:set app.example.com PORT=5000 </code></pre> There's a few more configuration details that need to be set. First, you'll need to tell Lucky the database details that are set in Dokku. Run the below command to get the database URL.
`dokku postgres:info exampledb </code></pre> Set the DATABASE_URL</code> environment variable from the above output.`
`dokku config:set app.example.com DATABASE_URL=postgres://... </code></pre> Next, Lucky needs a secret key environment variable. In your app directory on your local machine run the following command which will generate a secure key.`
`lucky gen.secret_key </code></pre> Then, back on your remote Dokku server add it to the SECRET_KEY_BASE</code> environment variable.`
`dokku config:set app.example.com SECRET_KEY_BASE=... </code></pre> If you're planning to send emails through the app you'll also need to set SEND_GRID_KEY</code> key, otherwise, change config/email.cr</code> to use Carbon::DevAdapter.new</code> in production (and make sure to commit!)`
`dokku config:set app.example.com SEND_GRID_KEY=... </code></pre>`Your server is almost ready for deployment. If you're using a server with 2GB of RAM or less, you'll need to set up a Swap. Without it the deployment process will most likely run into memory issues. Checkout this tutorial for setting up a Swap</a>. A 1G Swap should be more than enough. Step 2 - Ready the app for deployment</h2> Back in your local app add a new file called .buildpacks</code> with the following contents https://github.com/heroku/heroku-buildpack-nodejs https://github.com/luckyframework/heroku-buildpack-crystal </code></pre> Step - 3 Deploy</h2> Make a new commit. Finally you're ready to deploy. Run the following commands locally. The first will add your server as a remote origin for your git repo. The second will push the code to the server. git remote add dokku dokku@ip:app.example.com git push dokku master </code></pre> Step 4 - Set up SSL</h2> Dokku lets you easily set up a Lets Encrypt SSL certificate. Run the following commands to do so dokku config:set --no-restart app.example.com DOKKU_LETSENCRYPT_EMAIL=your.email@example.com dokku letsencrypt app.example.com </code></pre>

Adding RSS Feeds to a Lucky app

2019-06-13T00:00:00+00:00

Just a quick post for anyone looking to implement RSS Feeds in Crystal Lucky Framework. This post works with Lucky 0.14.1 but it should work with 0.15 as well.

Thanks to @paulcsmith</a> and @jeremywoertink</a> for helping me work this out in Gitter.

First, create an Action</code> that inherits from Lucky::Action</code>. We’ll add a method called xml</code> which can be called in each of your actions, passing in the data for the feed. The xml</code> method will then create the xml string with Crystal’s built in XML Builder and iterate over the data that you pass in.

# src/actions/xml_action.cr
</span>require </span>"</span>xml</span>"
</span>abstract class </span>XMLAction </span>< Lucky::Action
</span>    </span>def </span>title
</span>        "</span>Website RSS Feed</span>"
</span>    </span>end
</span>
</span>    </span>def </span>description
</span>        "</span>Updates for Website</span>"
</span>    </span>end
</span>
</span>    </span>def </span>link
</span>        "</span>https://websiteurl.dev</span>"
</span>    </span>end
</span>    
</span>    </span>private def </span>xml</span>(articles : </span>ArticleQuery</span>)
</span>        string = </span>XML</span>.build(</span>indent: </span>"  ", </span>encoding: </span>"</span>UTF-8</span>") </span>do </span>|</span>xml</span>|
</span>            xml.element(
</span>                "</span>rss</span>", 
</span>                </span>version: </span>"</span>2.0</span>", 
</span>                "</span>xmlns:dc</span>": "</span>http://purl.org/dc/elements/1.1/</span>",
</span>                "</span>xmlns:content</span>": "</span>http://purl.org/rss/1.0/modules/content/</span>",
</span>                "</span>xmlns:atom</span>": "</span>http://www.w3.org/2005/Atom</span>",
</span>                "</span>xmlns:media</span>": "</span>http://search.yahoo.com/mrss/</span>"
</span>                ) </span>do
</span>                xml.element("</span>channel</span>") </span>do
</span>                    xml.element("</span>title</span>") { xml.cdata title }
</span>                    xml.element("</span>description</span>") { xml.cdata description }
</span>                    xml.element("</span>link</span>") { xml.text link }
</span>                    xml.element("</span>generator</span>") { xml.text "</span>Lucky Framework</span>" }
</span>                    xml.element("</span>lastBuildDate</span>") { xml.text </span>Time</span>.utc_now.to_s }
</span>                    xml.element("</span>atom:link</span>") { 
</span>                        xml.attribute "</span>href</span>", "</span>#{</span>link</span>}#{</span>request.path</span>}</span>"
</span>                        xml.attribute "</span>rel</span>", "</span>self</span>"
</span>                        xml.attribute "</span>type</span>", "</span>application/rss+xml</span>"
</span>                    }
</span>                    xml.element("</span>ttl</span>") { xml.text "</span>60</span>" }
</span>                    articles.each </span>do </span>|</span>article</span>|
</span>                        xml.element("</span>item</span>") </span>do
</span>                            # title, description, link, category, dc:creator, pubDate, content:encoded
</span>                            xml.element("</span>title</span>") { xml.cdata article.title }
</span>                            </span>if</span> article.meta_description
</span>                                xml.element("</span>description</span>") { xml.cdata article.meta_description.not_nil! }
</span>                            </span>end
</span>                            xml.element("</span>link</span>") { xml.text "</span>#{</span>link</span>}</span>articles/</span>#{</span>article.slug</span>}</span>" }             xml.element("</span>dc:creator</span>") { xml.cdata "</span>Author Name</span>" }
</span>                            xml.element("</span>pubDate</span>") { xml.text article.created_at.to_s }
</span>                            </span>if</span> article.og_image
</span>                                xml.element("</span>media:content</span>") </span>do
</span>                                    xml.attribute "</span>url</span>", "</span>article.og_image</span>"
</span>                                    xml.attribute "</span>medium</span>", "</span>image</span>"
</span>                                </span>end
</span>                            </span>end
</span>                            </span>if</span> article.content
</span>                                content = </span>Markdown</span>.to_html(article.content.not_nil!)
</span>                                xml.element("</span>content:encoded</span>") { xml.cdata content }
</span>                            </span>end
</span>                        </span>end
</span>                    </span>end
</span>
</span>                </span>end
</span>            </span>end
</span>        </span>end
</span>        </span>Lucky</span>::</span>TextResponse</span>.</span>new</span>(</span>context</span>, </span>content_type: </span>"</span>text/xml; charset=utf-8</span>", </span>body:</span> string </span>status: </span>200</span>)
</span>    </span>end
</span>end
</span></code></pre>
Although this abstract class looks quite large it’s not really doing much except generating the XML to output to the browser. By doing this it will greatly simplify our action classes.</p>
In the example we’re passing in an ArticleQuery</code> which you will need to implement in your own app. For reference, mine has a scope for published</code> so I can keep unpublished articles from being viewed.</p>
class </span>ArticleQuery </span>< Article::BaseQuery
</span>  </span>def </span>published
</span>    published_at.lte(</span>Time</span>.now)
</span>  </span>end
</span>end
</span></code></pre>
The Article</code> model has the following attributes: title</code>, meta_description</code> (optional), slug</code>, content</code> (optional), og_image</code> (optional). You will need to update this for your own purposes as well.</p>
At the end of the XMLAction#xml</code> method we’re using Lucky::TextResponse</code> to send the XML string to the browser. Note that application/rss+xml</code> is the proper content type to respond with, however, if you want it to be viewable in a web browser you need to use text/xml; charset=utf-8</code> (This is how Ghost does it at least).</p>
Example Action</h2>
Since all the XML logic is in the XMLAction</code> we can make our actions really clean. In the example below Rss::Index</code> overrides the feed title and then passes in a list of published articles through the xml</code> method.</p>
# src/actions/rss/index.cr
</span>class </span>Rss::Index </span>< ::XMLAction
</span>
</span>    </span>def </span>title
</span>        "</span>Latest Dailies</span>"
</span>    </span>end
</span>
</span>    get "</span>/feeds/all.rss</span>" </span>do
</span>        articles = </span>ArticleQuery</span>.</span>new</span>.published.published_at.desc_order
</span>        xml articles
</span>    </span>end
</span>
</span>end
</span></code></pre>
Creating a Serializer</h2>
Although we have a working RSS feed, we can go one step further and create an ArticleXmlSerializer</code> to handle the XML, rather than using the XMLAction</code>. </p>
We'll pass this Serializer output to the modified XMLAction</code></p>
# src/actions/xml_action.cr
</span>abstract class </span>XMLAction </span>< Lucky::Action
</span>    </span>private def </span>xml</span>(body : </span>String</span>)
</span>        </span>Lucky</span>::</span>TextResponse</span>.</span>new</span>(</span>context</span>, </span>content_type: </span>"</span>text/xml; charset=utf-8</span>", </span>body:</span> body, </span>status: </span>200</span>)
</span>    </span>end
</span>end
</span></code></pre>
# src/serializers/article_xml_serializer.cr
</span>require </span>"</span>xml</span>"
</span>class </span>ArticlesXmlSerializer </span>< Lucky::Serializer
</span>
</span>    </span>property</span> title : </span>String </span>= ""
</span>    </span>property</span> description : </span>String </span>= ""
</span>    </span>property</span> base_url : </span>String </span>= "</span>https://example.dev</span>"
</span>    </span>property</span> path : </span>String </span>= ""
</span>
</span>    # You can set the instance vars directly. This elininates some code and also is now compile time safe!
</span>    # That means if you forget one of these arguments, it is the wrong type, or you have a typo, Crystal will let
</span>    # you know at compile-time
</span>    </span>def </span>initialize</span>(@</span>articles </span>: </span>ArticleQuery</span>, @</span>title</span>, @</span>description</span>, @</span>base_url</span>, @</span>path</span>)
</span>    </span>end
</span>
</span>    </span>def </span>render
</span>        </span>XML</span>.build(</span>indent: </span>"  ", </span>encoding: </span>"</span>UTF-8</span>") </span>do </span>|</span>xml</span>|
</span>            xml.element(
</span>                "</span>rss</span>", 
</span>                </span>version: </span>"</span>2.0</span>", 
</span>                "</span>xmlns:dc</span>": "</span>http://purl.org/dc/elements/1.1/</span>",
</span>                "</span>xmlns:content</span>": "</span>http://purl.org/rss/1.0/modules/content/</span>",
</span>                "</span>xmlns:atom</span>": "</span>http://www.w3.org/2005/Atom</span>",
</span>                "</span>xmlns:media</span>": "</span>http://search.yahoo.com/mrss/</span>"
</span>                ) </span>do
</span>                xml.element("</span>channel</span>") </span>do
</span>                    xml.element("</span>title</span>") { xml.cdata title }
</span>                    xml.element("</span>description</span>") { xml.cdata description }
</span>                    xml.element("</span>link</span>") { xml.text base_url }
</span>                    xml.element("</span>generator</span>") { xml.text "</span>Solo</span>" }
</span>                    xml.element("</span>lastBuildDate</span>") { xml.text </span>Time</span>.utc_now.to_s }
</span>                    xml.element("</span>atom:link</span>") { 
</span>                        xml.attribute "</span>href</span>", "</span>#{</span>base_url</span>}#{</span>path</span>}</span>"
</span>                        xml.attribute "</span>rel</span>", "</span>self</span>"
</span>                        xml.attribute "</span>type</span>", "</span>application/rss+xml</span>"
</span>                    }
</span>                    xml.element("</span>ttl</span>") { xml.text "</span>60</span>" }
</span>                    @</span>articles</span>.each </span>do </span>|</span>article</span>|
</span>                        xml.element("</span>item</span>") </span>do
</span>                            xml.element("</span>title</span>") { xml.cdata article.title }
</span>                            </span>if</span> article.meta_description
</span>                                xml.element("</span>description</span>") { xml.cdata article.meta_description.not_nil! }
</span>                            </span>end
</span>                            xml.element("</span>link</span>") { xml.text "</span>#{</span>base_url</span>}</span>/articles/</span>#{</span>article.slug</span>}</span>" }
</span>                            xml.element("</span>dc:creator</span>") { xml.cdata "</span>Author Name</span>" }
</span>                            xml.element("</span>pubDate</span>") { xml.text article.created_at.to_s }
</span>                            </span>if</span> article.og_image
</span>                                xml.element("</span>media:content</span>") </span>do
</span>                                    xml.attribute "</span>url</span>", "</span>article.og_image</span>"
</span>                                    xml.attribute "</span>medium</span>", "</span>image</span>"
</span>                                </span>end
</span>                            </span>end
</span>                            </span>if</span> article.content
</span>                                content = </span>Markdown</span>.to_html(article.content.not_nil!)
</span>                                xml.element("</span>content:encoded</span>") { xml.cdata content }
</span>                            </span>end
</span>                        </span>end
</span>                    </span>end
</span>                </span>end
</span>            </span>end
</span>        </span>end
</span>    </span>end
</span>end
</span></code></pre>
Finally, here's the new action</p>
# src/actions/rss/index.cr
</span>class </span>Rss::Index </span>< ::XMLAction
</span>
</span>    get "</span>/feeds/all.rss</span>" </span>do
</span>        articles = </span>ArticleQuery</span>.</span>new</span>.published.published_at.desc_order
</span>        xml </span>ArticlesXmlSerializer</span>.</span>new</span>(articles, </span>title: </span>"</span>Feed Name</span>", </span>description: </span>"</span>Here's the descr</span>", </span>path:</span> request.path).render
</span>    </span>end
</span>
</span>end
</span></code></pre>

- Lucky

How to deploy a Crystal Lucky application with Dokku on Ubuntu 18.04

What is Lucky?</h3>
Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.</p>

What is Dokku?</h3>
Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.</p>

Adding RSS Feeds to a Lucky app

- Lucky

How to deploy a Crystal Lucky application with Dokku on Ubuntu 18.04

What is Lucky?</h3> Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.</p>

What is Dokku?</h3> Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.</p>

Prequisites</h2> Crystal 0.34.0 installed locally</li> A fresh Lucky application installed and running locally.</li> Basic knowledge of Git.</li>

Adding RSS Feeds to a Lucky app

What is Lucky?</h3>
Lucky is a web framework written in Crystal</a>. Crystal is a programming language with syntax inspired by Ruby but with speeds similar to that of C.</p>

What is Dokku?</h3>
Dokku is a small PaaS service powered by Docker that you can run on your own servers. Think of it as a self-hosted command-line Heroku</a>.</p>