DEV Community: Martin Vandersteen

Deploying a Laravel app using Dokku

Martin Vandersteen — Fri, 19 Nov 2021 18:24:55 +0000

Introduction

Dokku is basically a self-hosted Heroku. It allows you to deploy your apps with a simple git push and it'll handle all the building and deploying automatically.

After having trouble finding an up-to-date and exhaustive how-to guide, I decided to write the steps down, It'll help me later and hopefully you as well ? Here are the steps I went through !

Setup your server

Create a DigitalOcean Dokku droplet or any other basic Ubuntu/Debian Server on which you installed Dokku
(facultative) Point a domain or Sub-domain to your Dokku installation
Visit your server's IP in your browser to finish the Dokku setup, make sure the SSH key is the correct one. Enter your Top Level Domain in the hostname field. I chose to use the virtualhost naming for my Dokku apps, I think it makes more sense for web apps!
Install the MySQL plugin for Dokku on your server

dokku plugin:install https://github.com/dokku/dokku-mysql.git mysql

(optional) Install the Let's Encrypt plugin if you want free SSL certificates

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Project Setup

Add PHP extension requirements to composer.json. This tells Dokku to activate those extensions on your server. Here are the ones I needed as example !

"require": {
  "ext-bcmath": "*",
  "ext-ctype": "*",
  "ext-curl": "*",
  "ext-exif": "*",
  "ext-fileinfo": "*",
  "ext-gd": "*",
  "ext-json": "*",
  "ext-mbstring": "*",
  "ext-pdo": "*",
  "ext-openssl": "*",
  "ext-tokenizer": "*",
  "ext-xml": "*",
  "ext-zip": "*"
}

After making the changes in composer.json you'll need to update it using composer update. You might encounter problems with the PHP extensions not being installable on your local env, in that case use composer update --ignore-platform-reqs to avoid installing them.
Add a build script to package.json, it will be run automatically on deploy by Dokku

"scripts": {
    "production": "mix --production",
    "build": "npm run production"
  },

Make sure your config/database.php has this line in the 'mysql' config :
'url' => env('DATABASE_URL'),
Create a Procfile (a file named Procfile at the root of the project). The release part contains the command that'll be run right after a build. The web part specifies the web server to run, here we simply run the default PHP server from Heroku and point it to the public folder

release: php artisan migrate --force
web: vendor/bin/heroku-php-apache2 public/

Specify the buildpacks you'll need in a .buildpacks file at the root of the project. You can see these as "build steps" before putting your application online. heroku-buildpack-php install your composer packages (amongst other things) and heroku-buildpack-nodejs install your npm dependencies and runs your build script.

https://github.com/heroku/heroku-buildpack-php
https://github.com/heroku/heroku-buildpack-nodejs

Dokku Setup

Create the app on the Dokku server with this command
dokku apps:create {name_of_your_app}
Add the git remote on your local dev environment with :
git remote add {remote_name} dokku@{server_url}:{app_name}
remote_name can be whatever. I use "staging" and "production" for example. app_name is the name you gave your Dokku app at the previous step.
Set up all your environment variables on the server using the dokku config:set {your_app_name} VAR=VALUE VAR2=VALUE2 ... command. Don't forget to mention an APP_KEY, APP_ENV, APP_URL, etc !
Create a MySQL database and link it to your app (your-db-name can be anything)

dokku mysql:create {your-db-name}
dokku mysql:link {your-db-name} {your_app_name}

Get the MySQL connection URL (mysql://user@example...) and set it as a variable for your app

dokku mysql:info {your-db-name} --dsn
dokku config:set {your_app_name} DATABASE_URL={connection_string_from_previous_command}

Deployment

Push your app to your Dokku server using : git push {remote_name}

(optional) Add a Let's encrypt certificate to your app !

Setup your contact email for Let's encrypt and generate your certificate

dokku config:set --no-restart {your_app_name} DOKKU_LETSENCRYPT_EMAIL={your_email_address}
dokku letsencrypt:enable {your_app_name}

All done 💃

Enjoy your app !

HTTP to HTTPS Redirection with Laravel Vapor

Martin Vandersteen — Sun, 03 Oct 2021 11:10:37 +0000

One of the limitations of Laravel Vapor is the inability to serve HTTPS. This isn't because of Vapor though, it comes from the Api Gateways from AWS that Vapor is built on. The problem with that is that when browser try to reach your domain via HTTP, nothing happens and they get an error screen, this is annoying for users that simply type your domain name in the url bar on IOS Safari for example as it won't try to contact the HTTPS port and just fail.

After two days of fighting with Cloudfront and Vapor, I finally got it working! With one caveat: If I change the domains associated to my Vapor environment in vapor.yml, I will experience a small downtime.

Important thing to note, this cannot work with the default SESSION_DRIVER which is the cookie driver as the headers become too large.

I'm using dynamodb as driver. Also, I'm using Api Gateway V2 and Route 53 as DNS so Vapor handles my DNS records ! If Vapor doesn't handle your DNS records you might be able to bypass some of this by changing the DNS records yourself to point at your Cloudfront distribution. In my case it would make my deployments fail.

Try this on a staging environment and test everything out carefully before trying it on production. Try to log in etc to make sure sessions work as well!

For the example, well say that we have a site that is currently deployed on example.com and www.example.com.

Creating the Cloudfront distribution

The idea is pretty simple, we'll put a Cloudfront distribution in front of our Api Gateway to act as a reverse proxy and redirect port 80 to port 443 when applicable.

Create a new Cloudfront distribution and use a subdomain of your choice as the origin url, that will be the new url of our Api Gateway that we will setup later on. Let's use gateway.example.com !

Give it a name of your liking then scroll down to the User section and select "Redirect HTTP to HTTPS" as User protocol policy and "GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE" as Allowed HTTP methods.

Regarding the Cache settings, select the "Legacy cache settings" and select "All" for Headers, Request query and Cookies.

In the Settings section, select the pricing category that makes the most sense to you, I'm using "Only Northern America and Europe" but it depends where your users are.

As "Alternative Domain Names", make sure to add www.example.com and example.com. Then, right under that, create an SSL certificate for those. I just used a wildcard certificate (*.example.com, example.com). You might need to add gateway.example.com in there but I don't think so !

Once you're done, click the create button and you're good to go !

Updating vapor.yml

The domains section of your vapor.yml should look a little bit like this by now :

domain:
  - www.example.com
  - example.com

Change it to this :

domain: gateway.example.com

And, once you're ready, deploy your application but BE AWARE that your application won't be reachable until you complete the next step (pretty fast).

Creating the Custom Domains on the Api Gateway

Go to your Api Gateway settings on AWS, in the Custom Domains section. Your www.example.com and example.com domains should have disappeared (deleted by Vapor) after the deployment. You simply need to recreate them both (don't forget to attach the certificate, you normally created one already via Vapor beforehand when attaching your custom domain for the first time).

Then, for both of those custom domain, setup the API Mappings to be the same as the ones created by Vapor on gateway.example.com. Select the right API Endpoint and Step (there is only one most of the time) then click save !

Do that for both domains and, after a few seconds, your app should now be accessible and redirect HTTP to HTTPS successfully :)

Conclusion

I'm by no means an AWS expert so there might be ways to do this in a safer or more optimized way, if that's the case don't hesitate to comment down below.

As I said above, if you change the domains in your vapor.yml, you will need to re-do the last step so keep that in mind. I will personnaly work on creating an after-deploy script for Vapor that will ensure those Custom Domains exist and re-create them if they don't !

Why I use Laravel as a Rails aficionado

Martin Vandersteen — Thu, 05 Aug 2021 19:26:05 +0000

I've been building web products professionnally and for fun for more than 7 years now. Despite being a complete Ruby on Rails fan (my first love) and having first experienced Laravel in the worst ways possible (taking over a legacy SaaS that was a complete mess), I still decided to use Laravel for my next major projects.

Both present similar MVC structures and similar functionalities, but they have quite different ecosystems. To me, being a good developer means choosing the right tool for the job, here are some reasons why I chose Laravel over Rails for those applications.

The ecosystem

Thanks to Tailor Otwell and others, there are a lot of VERY powerful satellite packages and tools that'll make you win precious time when building web products. Here are some of the ones that drove my decision :

Laravel Sail

Super easy development environment : $ sail up and you're good to go ! It spins up a web server, database, redis server and even mailhog to monitor your emails. All through Docker🐋 so you don't pollute your computer with useless servers that will clash with your other development projects.

Laravel Breeze & Jetstream

Thanks to those, you can start your application with all the boring authentication part pre-made for you. This includes signup, login, profile settings, dashboard, email verification & forgot password, password change, 2FA, .. Such a huge timesaver !

Laravel Nova

Powerful, beautiful & customizable admin ! Quite easy to install and to extend, with a lot of very useful plugins that'll make your life way easier. Building admins for web apps is a big part of the development time and any time saved is a big money saver, as long as the quality remains.

Laravel Vapor

Vapor turns your app into a Serverless app that autoscales in a hearthbeat. It manages your AWS ressources for you and allows you to change things in your Cloud with simple commands. It will save you weeks of handling your servers, I really think it has a crazy good Return On Investment for small to mid-sized applications. Focus on building your app and not on fiddling in AWS !

Statamic

Statamic is a pretty powerful and modern CMS that'll get you out of your Wordpress nightmares. Simple and efficient ! It recently saved me when I needed to build a BIG application that was a mix of a Website, CMS, CRM and E-commerce. Statamic made it possible for my client to edit pages & products in an efficient way while giving me the whole power of Laravel to meet requirements for the CRM aspect of things.

Laravel Spark

I personally never used it but it seems to be the Laravel Jetstream of SaaS products ! (It actually plays along well with Jetstream & Breeze) It handles subscriptions, payment providers & invoices for you so you can focus on the actual value your app brings.

The community

Pretty simple and straightforward but as there are more people using Laravel, it's easier to find answers to your problem on the web as well as finding help !

But that was not the deciding factor for me as, in my opinion, Rails is often easier to understand and more logical than Laravel. The main reason why the community is so important to me is that I'm making it easy for my clients to find new developers later on, as they will need someone to maintain and improve on the application that I built someday. There are a lot more people that use PHP in the world than Ruby and it's important to keep that in mind when you build an application that will be the epicenter of someone's business.

Conclusion

I'm still in love with Rails ! And I love that it keeps growing so well and evolving (can't wait to try Hotwire and compare it with Livewire), and it still is one of my favourite tools.

I just think it's important to be flexible and to be able to avoid getting stuck with one framework the becomes a Bible you franctically shake in front of everybody that uses something else!

Be curious and open to new things, give it a look and objectively assess if it's for you, or not, and if it actually brings new value to the programming world. There are tons of frameworks popping up everyday and while a lot are probably good, only a few will really fit you and make your work more efficient.

What's your take on this ? How do you position yourself in this world of frameworks ? 😜

Simple i18n for StimulusJS !

Martin Vandersteen — Tue, 23 Mar 2021 15:04:06 +0000

I recently had to setup internationalization on my website Feeka.studio which is only built with HTML/SCSS/StimulusJS and a few JS libraries.

Surprisingly enough, I didn't find much material on how to easily implement it with a Stimulus controller and I spent some time researching in order to make it work. I hope this short walkthrough will help other people in the same situation !

The HTML

For this example, I created a very simple layout with a banner containing a language switcher and a catchline, along with a section holding some random content. I also sprinkled a bit of CSS on it to make it a bit more organized, everything is in the Codepen at the end of the article.

Here is what it looks like :

<section class="banner">
  <div class="switcher" data-controller="locale"></div>
  <div class="catchphrase" data-i18n="[html]catchphrase"></div>
</section>
<section class="content" data-i18n="content">
</section>

Setting up our Stimulus controller

For this example, I will be creating a single "LocaleController". Keep in mind that I will be putting all of my Javascript in the same file here since I'm using Codepen, but it's always good to split the different parts of the application, for example the controller should be declared in its own file, and the i18n configuration we'll be writing later on should be in another one. Being organized and maintaining the separation of concerns makes our lives easier in the long run !

Here is the basis of my controller :

class LocaleController extends Controller {
  static targets = ['language'];

  get languages() { 
    return [
      { title: 'FR', code: 'fr' },
      { title: 'EN', code: 'en' }
    ];
  }

  initialize() {
    this.element.innerHTML = this.languages.map((locale) => {
      return `<span data-action="click->locale#changeLocale"
      data-locale="${locale.code}" data-target="locale.language">${locale.title}</span>`
    }).join('');
    this.setLocale('fr');
  }

  changeLocale(e) {
    this.setLocale(e.target.getAttribute("data-locale"));
  }

  setLocale(locale) {
    this.highlightCurrentLocale(locale);
  }

  highlightCurrentLocale(locale) {
    this.languageTargets.forEach((el, i) => {
      el.classList.toggle("active", locale !== el.getAttribute("data-locale"))
    });
  }
}

First of all, I'm defining a getter for our list of languages which for this example will be French and English. The title represents the text that should appear in the language switcher and the code is what we'll use to manage our translations with i18next later on, it could also be written using the standard 'fr-FR' notation.

In the initialize() function, I'm setting up my dynamic language switcher by iterating over the available languages and inserting a span for each of them, along with a data-action attribute that will call our changeLocale() function on click and a data-locale attribute that will make it easy to retrieve the language code when the element is clicked. I'm also manually setting the locale to French at the moment but that will be handled by i18next once we implement it.

Right now the changeLocale(e) function only makes sure we hide the current language in the switcher and show the other one. Using CSS, I made sure only the with the 'active' class is shown.

Here is the current state of things : https://codepen.io/martinvandersteen/pen/vYgEEMN

We just have a language switcher that switches when you click it, nothing crazy, but that'll change quickly !

Adding i18next in the mix

For this, I'm using some additional packages : 'i18next' that manages the bulk of the i18n job, 'loc-i18next' that will insert the translations in our HTML to make it a bit easier for us and 'i18next-browser-languagedetector' that does exactly what the name suggests ;)

Initializing our packages

At the top of my file, I'll be creating simple objects like these to make it easy to see on CodePen :

const frTranslations = {
  catchphrase: "Bienvenue sur <strong>DEV.TO</strong>",
  content: "Contenu statique de mon site internet"
};

const enTranslations = {
  catchphrase: "Welcome to <strong>DEV.TO</strong>",
  content: "Static content of my website"
};

In the production environment I'm putting all of my translations in two /locales/fr/global.json and /locales/en/global.json files, then I'm simply importing them when I'm initializing i18next, that makes it all a bit cleaner. But that'll do just fine for the sake of the example !

You can see that the "catchphrase" and "content" keys are actually the ones used in the [data-i18n] attributes in our HTML, that's what enables our 'loc-i18next' package to know where to insert the various translations in our file.

After writing down those translation objects, let's initialize i18next like so :

// We're telling i18next to use(LngDetector) which is the name I used to import our 'i18next-browser-languagedetector' package
const i18n = i18next.use(LngDetector).init({ 
  supportedLngs: ['fr', 'en'], // The list of languages we use
  fallbackLng: 'en', // The default language to use when no translations are found in the current locale
  detection: {
    order: ['navigator'] // What to infer the initial locale from, this is given by our LngDetector
  },
  resources: {
    fr: { translation: frTranslations }, // Specifying our translations
    en: { translation: enTranslations }
  }
}, function (err, t) {
  if (err) return console.error(err) // Writing down errors in the console if need be
});

We can then initialize 'loc-i18next' which will insert our translations in the DOM by specifying the HTML attribute we used to mark the places used for the content :

// We attach localize to our i18next instance and tell him to look for 'data-i18n' attributes
const localize = locI18next.init(i18next, {
  selectorAttr: 'data-i18n'
});

With everything setup, it's time to insert our i18next logic into our controller and make it all work together !

Updating the Controller

In our Initialize method, we'll simply wrap everything with our i18n.then(() => {}); call, that will make sure we only run that code after i18n has been fully initialized with the translations and current browser language, like so :

initialize() {
    i18n.then(() => {
      this.element.innerHTML = this.languages.map((locale) => {
        return `<span data-action="click->locale#changeLocale"
        data-locale="${locale.code}" data-target="locale.language">${locale.title}</span>`
      }).join('');
      this.setLocale(i18next.language);
    });
  }

Notice we're also setting the locale at the end of the function with setLocale(i18next.language), using the language automatically detected by our i18next LngDetector as argument.

Inside setLocale(locale), we'll make sure that we change the locale directly at the i18next level now, and we'll call the localize(selector) method from 'loc-i18next' in order to update the content according to the new language.

setLocale(locale) {
  i18next.changeLanguage(locale).then(() => {
    localize('[data-i18n]'); // localize() takes as argument a selector, by passing '[data-i18n]' we update all DOM elements that have a data-i18n attribute set
    this.highlightCurrentLocale();
  });
}

And we also have to update the "highlightCurrentLocale()" function so that it uses "i18next.language" to define the current locale used.

Conclusion

And voilà ! It is a pretty simple setup, so don't hesitate to build a bit on that basis, by changing part of the URL when the local changes and infering the locale from the URL/Browser cache/... You will find quite some documentation regarding the i18next package, even though a lot of it is about react-i18next, it still applies.

Here is the final codepen link : https://codepen.io/martinvandersteen/pen/abpbvgK

I hope it will help you setting up i18n on your own websites, cheers !