Minh Nguyen

March 2021 design iteration of my site

Tue, 23 Mar 2021 07:00:00 GMT

I’ve been documenting the current website codebase to understand it better. Guess that’s what happens when you pick up a system that you can easily start with, and get to learn over time as you need it.

I’m trying to structure this documentation off the Documentation System by Divio, which breaks the act of documenting down into 4 distinct sections: tutorials, how-to guides, references, and explanations. I might go further into this in a future blog post, so keep an eye out for that.

From the changes which are visible, I’ve made changes to the design which increases the width of the content section, provided your monitor reports at least 1920px width, which makes it better to view at higher resolutions. It was getting just a bit too narrow on my ultrawide monitor.

Secondly, you might have noticed at the end of articles that there’s a new footer at the bottom of each blog article. That will let you navigate to the next or previous article by chronological order. There’s also a section for comments, so readers can leave comments and questions, and I can respond to those without having to make a new post.

Lastly, I’ve made the link to the RSS feed a lot more visible, both in the main navigation and the footer component. There’s a bit of a small revolution in terms of how people ingest content and the mechanisms to do so, but RSS is pretty reliable. There’s plenty of programs/services that you can use, so I won’t detail them here, but if you find yourself reading a lot of articles online, it’s definitely a plus.

How to use MailHog in Lando

Mon, 08 Feb 2021 05:00:00 GMT

If you’ve ever needed a service to capture e-mails, MailHog is a pretty good choice. MailHog contains an SMTP server which you send messages to, simulating your production SMTP service, and provides a HTTP interface so you can see what’s being sent.

Photo by Charlotte Harrison on Unsplash.

It isn’t a substitute for your production mail service or e-mail client, so you’ll still need to plug it all in for testing, and make sure to check in a variety of e-mail clients. This is good if you need to debug why e-mail clients are rendering your messages strangely and need to experiment.

With that in mind, I’ll show you how to add a MailHog service in Lando via the Landofile .lando.yml.

Prerequisites

You know how to run Lando
You have an application which sends messages via SMTP

Setting up your Landofile

In your Landofile (.lando.yml), add a new section for services. If your Landofile already has one, you can append to it instead. Below I define a new service called mail:

# .lando.yml
# ...the rest of the YAML config sits above here

services:
  mail:
    type: mailhog

We’re almost ready to go, but we need to provide information about which services need to be able to access MailHog. To do that, define a key labelled hogfrom, and list all our services. In this case, appserver is responsible for sending our message:

# .lando.yml
# ...the rest of the YAML config sits above here

services:
  mail:
    type: mailhog
    hogfrom:
      - appserver

Run lando rebuild, which should rebuild your stack, including the new MailHog service. In the output where you see a list of URLs you can access your app from, you should now see a localhost URL that you can open to access the MailHog interface.

Configuring your web app

In your web app, you will need to change the SMTP configuration so it points at MailHog. In Drupal, this can be done by overriding the system configuration in settings.local.php. This may differ depending on your specific application, so I can’t help with that.

In terms of credentials and URLs, here is what you can use to connect to MailHog’s SMTP server:

Hostname: mail—same as the name we gave the service above
Port: 1025
Username: as desired
Password: as desired

Some questions

Couldn’t I just run MailHog outside of Lando or Docker?

Sure, but Lando exists as a way to lock down those tools so your colleagues don’t have to figure out how to install MailHog, or ask you how to install it.

Wasn’t MailHog development suspended?

It was for some time, but development picked up again and a new release 1.0.1 was put out August 12 2020. I was a bit surprised as well, since the last official release 1.0.0 was in 2017.

How to install ClamAV in Lando for Drupal

Tue, 02 Feb 2021 23:00:00 GMT

ClamAV is an antivirus software service which allows servers to scan for viruses. While it is notable for use in scanning for viruses on mail servers, we can also use it in our web applications to scan file uploads.

Photo by N Bandaru on Unsplash.

I’m doing some local development on a Drupal based site, which makes use of ClamAV through a contributed module to scan files uploaded to the site.

Having the module enabled but not having ClamAV on the system throws an error:

You could just uninstall the ClamAV module and work without it, but that introduces a potential gap in your test coverage—the behaviour of the site operates differently without the module installed, which could lead to issues that you don’t discover until later.

Prerequisites

You know how to run Lando
Your application is configured to scan file uploads e.g. in Drupal, the ClamAV module

Setting up your Landofile

In your Landofile (.lando.yml), we will use the services section to modify the main application service—in our case labelled appserver to install ClamAV:

# .lando.yml
# ...the rest of the YAML config sits above here

services:
  appserver:
    build_as_root:
      - apt-get update -y
      - apt-get install clamav clamav-daemon -y
      - echo "TCPSocket 3310" >> /etc/clamav/clamd.conf
      - freshclam
      - update-rc.d clamav-daemon enable
    run_as_root:
      - service clamav-daemon start

This sets up the commands to run that installs ClamAV, sets up the ability to connect to the service on port 3310, update the database definitions necessary to scan files, and then enable the ClamAV service.

Note here that we are using apt-get to install the packages as the base container images that Lando uses are from Debian. You may need to adjust if your base distribution is different.

Once the changes are made, rebuild the service with lando rebuild. This will relaunch your application, install ClamAV into your local container, and start it.

I can now load up my environment and confirm that ClamAV is successfully loaded, and that file uploads work:

Furthermore, we can use the EICAR test file to confirm that it does block viruses from being uploaded:

Possible future changes

I could set out these changes in a custom service, or alternatively use a prebuilt container for ClamAV. Of course, the current hosting environment assumes ClamAV running on localhost on a TCP port so it’s not practical to modify it for that yet.

Hopefully this has been a useful guide in how to have ClamAV set up for your Drupal site. If you’re not running Drupal, hopefully you’ll find it useful if you’re integrating ClamAV for your own applications and infrastructure.

Annotating my pages with microformats2 and h-entry

Wed, 30 Sep 2020 10:26:00 GMT

h-entry is an open microformat for datestamped content on the web. I was looking at ways to make my site a bit more open to syndication, and also as an alternative to RSS/Atom feeds. I haven’t seen major browsers pick up on these formats, but the main focus are IndieWeb readers, and I’m all for them.

Now, please note that this post isn’t much of a guide to implementing h-entry or other parts of the microformats2 spec on your site, as it is a summary of I went about implementing it for this website.

What it looks like

h-entry looks something like this, after parsing a HTML page:

{
  "items": [
    {
      "type": [
        "h-entry"
      ],
      "properties": {
        "name": [
          "My blog post"
        ],
        "author": [
          {
            "value": "John Smith"
          }
        ],
        "published": [
          "2020-01-01 12:00:00"
        ],
        "summary": [
          "A short summary of my blog post, and what you can do."
        ],
        "content": [
          {
            "value": "Starting paragraph of my blog post.",
            "html": "<p>Starting paragraph of my blog post.</p>"
          }
        ]
      }
    }
  ]
}

In short, there’s basically all of the information about the post, in a JSON object that could be easily be used as part of a different app. With that in mind, how does a parser go about doing this?

Elements of h-entry

h-entry itself is a what is known as a root class name. We can use it to define a h-entry, and it has a series of properties that the parser will determine, based on knowing that. Other root class names include:

h-adr
h-event
h-geo
h-item
h-product
h-recipe

You can find a more detailed list of these on the microformats2 page, along with examples and detailed descriptions.

Back to h-entry, we can establish this simply by naming it as a class:

<article class="h-entry">
...
</article>

and that’s it, our article is now parseable as it is, though it might not be very useful by itself. This is where we add some core h-entry properties!

h-entry properties

There’s quite an amount of these, so I’ll only go with the properties that I used for this site.

p-name

This represents the entry name or title. For the title, we just need to add this class to the element that contains it:

<h1 class="p-name">{post.frontmatter.title}</h1>

e-content

The full content of the entry in question i.e. the full body of the blog post:

<section class="e-content">...</section>

dt-published

The datestamp of when the entry was published:

<time class="dt-published" datetime="2020-09-29">29 September, 2020</time>

Implementing h-entry within a Gatsby content type

Let’s get topical! For this, I’m using Gatsby as my site generator, so in order to get this working for my blog post, I need to modify the template for the blog post’s render function (located in /src/templates/blog-post.js), which returns JSX as follows:

export default ({data}) => {
  const post = data.markdownRemark
  return (
    <Layout>
      <SEO title={post.frontmatter.title} description={post.excerpt} />
      <section className="h-entry">
        <h1 style={{marginBottom: `0.5rem`}} className="p-name">{post.frontmatter.title}</h1>
        { post.frontmatter.draft ? (
          `Draft`
        ) : (
          <time className="dt-published" dateTime={post.frontmatter.htmldate}>{post.frontmatter.date}</time>
        )}
        <section className="e-content" dangerouslySetInnerHTML={{ __html: post.html }} />
      </section>
    </Layout>
  )
}

You can see that the 2 section, the h1, and the time elements are updated as above to have the microformat2 elements defined via the className attribute. While I was able to get it working on these generic HTML elements, I wasn’t able to get it working for the time element, which was previously a separate element called <DateTime>. I couldn’t figure it out, so I reverted to using the base element that it represented.

Running NixOS in Production

Thu, 17 Sep 2020 08:16:00 GMT

NixOS logo created by Tim Cuthbertson (@timbertson), licenced under CC-BY 4.0.

I’ve moved some items from my previous site infrastructure over to a VPS powered running NixOS in the past weekend. What made me do it? There were a few reasons that came to mind for it.

The first is that I’m sort of done running on OpenVZ—the performance is pretty bare compared to other options out there. There’s only a few choices for operating systems to run on it. Ubuntu 16.04 (Xenial) is okay to work with, but on the limited resources, things always took a lot longer than they should have, whether it was running Ghost or trying to build this site on Gatsby.

Another reason for doing this is that I don’t remember a lot of the things I did setting up the site. Could I tell you I installed Certbot? Nope. Could I recite the hundred word set of compiler arguments to make I compiled nginx with Pagespeed support? Nope. Would I know how to update PHP from 7.2 once it reaches end of life? Nope—I’d have to look that one up (and I already have to do that in my day to day work!).

I could have picked any other OS to operate, like Debian or CentOS. But I ended up on NixOS for the following reasons:

I wanted to learn more about NixOS, and how to run through application deployment and management to see how it stacks up against other methods.
The idea of declaring my system configuration as code I could deploy was interesting to me, since I spend a lot of time running through package installation and configuration in my day-to-day—making that process easier would definitely give me time to do other things.

Some of the details

For some context, I have Nix installed on my Arch Linux system (there’s a useful guide to install it on their wiki). From there, it was a matter of putting together a few pieces of configuration. The build script itself is powered by Elixir—mainly a result of the fact I couldn’t get the Haskell script in the guide I was following to work.

The VPS is an Amazon EC2 instance, which was created using the instructions provided by NixOS to launch a provided Amazon Machine Image (AMI).

The first stop is server.nix, which is built like this:

let
  nixos = import <nixpkgs/nixos> {
    configuration = import ./configuration.nix;
  };
in
  nixos.system

configuration.nix contains the bulk of the configuration which is set up on the system:

{config, pkgs, ...}:
let
  unstable = import <nixos-unstable> {};
in
{
  imports = [ <nixpkgs/nixos/modules/virtualisation/amazon-image.nix> ./users.nix ./firewall.nix ./webserver.nix ];
  ec2.hvm = true;
  networking.hostName = "mnguyen-nix-demo";
  environment.systemPackages = [
    unstable.caddy2
    pkgs.fish
    pkgs.htop
    pkgs.mosh
    pkgs.vim
  ];

  programs.fish.enable = true;

  # sudo without requiring password
  security.sudo.wheelNeedsPassword = false;

  ## Enable BBR module
  boot.kernelModules = [ "tcp_bbr" ];

  ## Network hardening and performance
  boot.kernel.sysctl = {
    # Disable magic SysRq key
    "kernel.sysrq" = 0;
    # Ignore ICMP broadcasts to avoid participating in Smurf attacks
    "net.ipv4.icmp_echo_ignore_broadcasts" = 1;
    # Ignore bad ICMP errors
    "net.ipv4.icmp_ignore_bogus_error_responses" = 1;
    # Reverse-path filter for spoof protection
    "net.ipv4.conf.default.rp_filter" = 1;
    "net.ipv4.conf.all.rp_filter" = 1;
    # SYN flood protection
    "net.ipv4.tcp_syncookies" = 1;
    # Do not accept ICMP redirects (prevent MITM attacks)
    "net.ipv4.conf.all.accept_redirects" = 0;
    "net.ipv4.conf.default.accept_redirects" = 0;
    "net.ipv4.conf.all.secure_redirects" = 0;
    "net.ipv4.conf.default.secure_redirects" = 0;
    "net.ipv6.conf.all.accept_redirects" = 0;
    "net.ipv6.conf.default.accept_redirects" = 0;
    # Do not send ICMP redirects (we are not a router)
    "net.ipv4.conf.all.send_redirects" = 0;
    # Do not accept IP source route packets (we are not a router)
    "net.ipv4.conf.all.accept_source_route" = 0;
    "net.ipv6.conf.all.accept_source_route" = 0;
    # Protect against tcp time-wait assassination hazards
    "net.ipv4.tcp_rfc1337" = 1;
    # TCP Fast Open (TFO)
    "net.ipv4.tcp_fastopen" = 3;
    ## Bufferbloat mitigations
    # Requires >= 4.9 & kernel module
    "net.ipv4.tcp_congestion_control" = "bbr";
    # Requires >= 4.19
    "net.core.default_qdisc" = "cake";
  };

  # disable passwordless SSH
  services.openssh.passwordAuthentication = false;

  # Let trusted users upload unsigned packages
  nix.trustedUsers = ["@wheel"];

  # Clean up packages after a while
  nix.gc = {
    automatic = true;
    dates = "weekly UTC";
  };

  # Disable reinitialisation of AMI on restart or power cycle
  systemd.services.amazon-init.enable = false;

  swapDevices = [
    {
      device = "/swapfile";
      priority = 10;
      size = 1024;
    }
  ];

  systemd.services.fathom = {
    description = "Fathom Server";
    requires = ["network.target"];
    after = ["network.target"];
    wantedBy = ["multi-user.target"];

    serviceConfig = {
      Type = "simple";
      User = "minh";
      Restart = "on-failure";
      RestartSec = 3;
      WorkingDirectory = "/var/lib/fathom";
      ExecStart = "/home/minh/bin/fathom --config=/etc/fathom.env server";
    };
  };
}

imports pulls in specific NixOS configuration for EC2 which it’s running on, and I’ve started work separating out configuration to separate files, ./users.nix, ./firewall.nix, and ./webserver.nix.

Packages

You can see near the top of configuration.nix there’s a variable called environment.systemPackages. This lists all the additional software packages I want installed. In this case, I have fish, htop, mosh, and vim installed from the standard repo, as well as Caddy 2 from the unstable NixOS branch.

Swap

I don’t have any swap on the system, so the variable swapdevices is set to create a swap file at /swapfile. The size is defined in megabytes, so this file is 1 gigabyte in size.

Firewall

NixOS comes with a firewall setup out of the box to only be open for SSH on port 22. To change it up, we can set networking.firewall.allowedTCPPorts as a list of ports we want to be open.

I also want to move the default SSH port to something else, this is defined by services.openssh.listenAddresses.

In the end, my firewall.nix file looks like this:

{ config, pkgs, ...}:
{
  # SSHD Port reassignment
  services.openssh.listenAddresses = [
    { addr = "0.0.0.0"; port = 37586; }
  ];

  # Allowed TCP range
  networking.firewall.allowedTCPPorts = [ 80 443 37586 ];

  # Allow Mosh connections
  networking.firewall.allowedUDPPortRanges = [{ from = 60000; to = 60010; }];
}

Caddy server

Moving on, I set up the web server within webserver.nix:

{config, pkgs, ...}:
let
  unstable = import <nixos-unstable> {};
  caddyDir = "/var/lib/caddy";
  caddyConfig = pkgs.writeText "Caddyfile"
    ''{
  storage file_system {
    root /var/lib/caddy
  }
}
mnguyen.io {
  root * /srv/www/mnguyen.io
  file_server
  header / {
    X-Content-Type-Options "nosniff"
    X-Frame-Options "sameorigin"
    Referrer-Policy "no-referrer-when-downgrade"
    X-UA-Compatible "IE=edge,chrome=1"
    X-XSS-Protection "1; mode=block"
    Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    Content-Security-Policy "default-src 'self'; connect-src https://analytics.mnguyen.io 'self'; font-src 'self' data:; img-src https://analytics.mnguyen.io 'self' data:; script-src https://analytics.mnguyen.io 'self' 'unsafe-inline'; style-src 'unsafe-inline'; worker-src 'self'; prefetch-src 'self'; report-uri https://mnguyen.report-uri.com/r/d/csp/enforce; report-to https://mnguyen.report-uri.com/r/d/csp/enforce"
  }
}

www.mnguyen.io {
  redir https://mnguyen.io{uri}
}

analytics.mnguyen.io {
  reverse_proxy localhost:9000
}
'';
in
{
  systemd.services.caddy = {
    description = "Caddy web server";
    after = [ "network-online.target" ];
    wants = [ "network-online.target" ];
    wantedBy = [ "multi-user.target" ];
    serviceConfig = {
      User = "caddy";
      Group = "caddy";
      ExecStart = ''
        ${unstable.caddy2}/bin/caddy run --config ${caddyConfig} --adapter caddyfile
      '';
      ExecReload = ''
        ${unstable.caddy2}/bin/caddy reload --config ${caddyConfig} --adapter caddyfile
      '';
      TimeoutStopSec = "5s";
      LimitNOFILE = 1048576;
      LimitNPROC = 512;
      PrivateTmp = true;
      ProtectSystem = "full";
      AmbientCapabilities = "cap_net_bind_service";
    };
  };

  users.users.caddy = {
    group = "caddy";
    uid = config.ids.uids.caddy;
    home = caddyDir;
    createHome = true;
    extraGroups = [ "users" ];
  };

  users.groups.caddy.gid = config.ids.uids.caddy;
}

What this does is set up the Caddyfile that Caddy 2 will be using, as well as the systemd service which sets up the command, sets the capabilities of the service so it can run at lower port numbers (below 1024 to be precise), and sets up a dedicated caddy user which it will run under.

Users

Speaking of which, users in NixOS can be defined in a few lines. This is what can go into users.nix:

{ config, pkgs, ...}:
{
  users.users.minh = {
    isNormalUser = true;
    extraGroups = ["wheel"];
    shell = pkgs.fish;

    # password = "my secure password";
    # hashedPassword = "$6$qTK.7QsrnONOr$ZsAfPlnEPLtpiO9j1qp/POkDga2LtK1UOD0nrG497CegYEq5e.E6iHf5tDqwfLViBSWEsw8sn5t885p6HyRgS1";

    openssh.authorizedKeys.keys = [
      "ssh-rsa PUBLICKEYHERE"
    ];
  };
}

The flag isNormalUser tells NixOS to give us a home directory at /home/minh. I then set up sudo access by adding this user to the wheel group, set the shell to fish, and set the allowed SSH key that is allowed to access this user on the system—I cannot sign in with a password unless it’s explicitly set.

If I did want to set a password, I could use the insecure option password which is a string, or slightly more secure passwordHash (which uses a hash generated from the command mkpasswd -m sha-512, detailed on the passwordHash options page)

Fathom analytics

I pulled the last public available release of Fathom Lite from their repository, and created a systemd service file to run it. I was worried for a bit that it wouldn’t run, as there were a lot of discussions going on the community forums about having to patch or otherwise emulate a standard Linux system to make binaries work.

Thankfully, Fathom isn’t one of those programs, and it worked flawlessly without any other work. It’s not packaged for NixOS, so this is probably the least NixOS part of this system.

Building NixOS

There are 2 commands to build our NixOS packages and send it to our remote system, then there’s 2 other commands to switch profiles and activate our new setup:

nix-build: which builds the NixOS packages
nix-copy-closure: sends the NixOS packages to our remote
nix-env: Set the Nix profile to our uploaded packages
switch-to-configuration: Switch the system configuration to our new configuration

These all come together in an Elixir script:

server_raw = File.read!("server_address.txt")
server_processed = String.replace(server_raw, "\n", "")

defmodule Build do
  def upload_to_system(path, address) do
    {path_str, _status} = path
    fixed_path_str = String.replace(path_str, "\n", "")
    System.cmd("nix-copy-closure", ["--to", "--use-substitutes", address, fixed_path_str])
    Build.activate_nix(path_str, address)
  end

  def activate_nix(path, address) do
    profile = "/nix/var/nix/profiles/system"
    System.cmd("ssh", ["#{address}", "sudo nix-env --profile #{profile} --set #{path}"])
    System.cmd("ssh", ["#{address}", "sudo #{profile}/bin/switch-to-configuration switch"])
  end
end

System.cmd("nix-build", ["server.nix", "--no-out-link"])
  |> Build.upload_to_system(server_processed)

Running the script runs all of those commands sequentially, and executes all the above. One thing I note about this is that the script hangs if there’s an issue with any of the configuration files, which could lead to a server that’s unresponsive. You may need to power cycle your remote instance if that happens.

Concluding remarks

I learned quite a bit about NixOS, but like most things involved quite a bit of trial and error. Thankfully, having this sort of configuration means I can easily rebuild the system (such as when I found myself unable to connect via SSH when I changed the port but didn’t realise the firewall needed to be changed as well).

If you’re interested in NixOS, I’d encourage you to take a look.

Useful links

In case you wanted to delve further into some of the resources I looked up while I was getting this set up:

Deploying NixOS to Amazon EC2 by Type Classes: This was very useful starting out to understand how to build NixOS locally, and how to ship it off to a different installation.
Running a local dns and web server by José Luis Lafuente: I found the section to define the custom systemd service very useful (just a heads up you want to set home for the user in that config to the Caddy data directory—mine was /var/lib/caddy)

My Gatsby setup

Sun, 14 Jun 2020 11:17:00 GMT

Gatsby is a framework which employs React to build sites just like the one you see here. There’s quite a few parts to it, so I’ll go over the setup in this post, and the things that I’ve added to make the experience pleasant, both for users (to read and explore) and myself (to work on and iterate).

Base styles and components

While there’s a few ways of setting up styles on the site, I have 2 primary methods of styling:

A global CSS file which contains styling which is common across components.
CSS-in-JS, styles in components that are specific to individual components, such as layout, header, buttons.

Having tried both, it does feel a bit easier to separate concerns with styling—it’s a lot more difficult to have collisions with class naming. There’s an endless debate as to whether CSS-in-JS is the right approach or not, but that’s another article for another time.

As for the components themselves, they’re mostly straightforward to work with. Below is a sample from my DateTime component which is used in the articles section:

// file: src/components/datetime.js
import React from "react"

const DateTime = props => (
  <p>
    <time datetime={props.datetime}>{props.dateformatted}</time>
  </p>
)

export default DateTime

This can then be used by other components like so:

// file: src/components/recent_posts.js
...
const RecentPosts = () => {
  return (
    ...
    <DateTime datetime={node.frontmatter.htmldate} dateformatted={node.frontmatter.date} />
    ...
  )
}

export default RecentPosts

I’m sure I could make even better use of React, but the fact is that I don’t think I have that bigger picture just yet. Maybe I’ll make it possible to have a dark-mode toggle switch or something. One day.

Article rendering

Articles use gatsby-transformer-remark, which provides the ability to parse markdown files, and it exposes a way for additional plugins to do their thing.

I use the gatsby-remark-smartypants plugin to modify the output a little, including directional quotes, em-dashes, ellipses—things that make the reading experience a bit more pleasant.

Code blocks use gatsby-remark-prismjs, enabling syntax highlighting for code blocks like you see above. It has a variety of themes—I’ve opted to use a11y Dark for code blocks, due to the fact that it:

Looks nice—the colours help distinguish between different bits of code.
Contrasts nicely with the text blocks that go around it.

Images use gatsby-remark-images with the tracedSVG option so it’s possible to show a SVG placeholder, and then lazy load in images when the user scrolls it into view.

Typography

gatsby-plugin-typography provides Typography.js an easy way to define font choices and sizes, which are used for headings and content. I use Lato for the header fonts, as it became part of my branding and I thought it suitable here.

Literata was used for the main content, as I encountered it in the Android app of Google Play Books and I found it very easy to read.

Other things

Because this is a static generated site, we have to fit in a few more things which would normally be done by the CMS templating engine into the build:

gatsby-plugin-manifest: Creates a manifest file for progressive web app (PWA) support, used in conjunction with gatsby-plugin-offline.
gatsby-plugin-robots-txt: Generate a robots.txt at build—I’ve configured it to indicate the presence of the sitemap.xml file which is generated by gatsby-plugin-sitemap.
gatsby-plugin-feed: Provides support to subscribe to a RSS feed containing all my written articles.

Closing thoughts

Is it over-engineered? Perhaps—at the end of the day, I’m just using text files to produce and publish HTML pages.

However, it is a valuable learning experiment to play around and tinker, and I’m still learning things as I go.

Winter visit to the Blue Mountains

Sun, 11 Aug 2019 00:00:00 GMT

We went to the Blue Mountains region as celebration for my recent birthday. The Blue Mountains were only a short distance away from home, and we kind of wanted to get out of the house for a change. As we were making the road trip up, we noticed that the originally sunny weather had faded away, and it had gotten much more chilly as we ascended. The national weather bureau had reported that snow was possible over this weekend.

In the afternoon, we headed out to a couple of lookout points. Hargraves Lookout was quite an impressive, albeit a windy sight.

We made a visit to another trail over at Govetts Leap lookout. It was remarkable to me how the rockface was shaped over the Earth’s lifetime, and how long the whole process was.

Dinner was enjoyed at the Golf Club, which cooked a very nice steak. The car did chime up on the way over, warning us that the outside temperature had dipped to 3°C.

This was mainly due to the fact that there really isn’t much thought put into adding anti-freeze—most places in Australia don’t dip below 0°C (32°F). Not that we expected it to be a huge problem anyway, since we weren’t exactly aiming to let the car cool down completely, and the valley was low enough not to freeze over.

Saturday morning was quite cold. We had put on the wood burner the previous night, and had some luck keeping the flames up, but it had died down just as we were getting to bed. Overnight, the cabin had cooled down despite running the air conditioning unit at full blast.

Not having had breakfast, we made our way up the hill into town when we first saw some snow cover. It was a surreal experience.

Making the decision to return to Hargraves Lookout was a good choice—snow had only fallen in a few locations, and the lookout was one of those places.

Automatic updates for packages in CentOS

Sat, 06 Apr 2019 08:11:00 GMT

This guide sets up a tool called yum-cron which can handle unmanaged updates on your behalf at a scheduled interval. While this guide is for CentOS, you could apply it to other similar distros, such as Amazon Linux 2, Fedora, or Red Hat.

Things before you begin

You should have one of the above distros of Linux, which is connected to the internet. crond should also be installed and its associated service should be enabled and started.

If you’re going to enable automatic updates, be aware this does carry some risk—I wouldn’t recommend it if you have mission critical software or services running on your machine. Consider running automatic updates on a staging machine and schedule running updates yourself.

Overview

Install the yum-cron package
Configure yum-cron to your needs/wants
Enable and start the yum-cron service

Installing the package

First off, you should make sure that your system is up to date. On the assumption that you can elevate permissions through sudo, you can do that by running sudo yum update .

Once that’s done, you should be able to install yum-cron with the command sudo yum install yum-cron.

For the next part, check the contents of your /etc/yum/ directory. Here’s mine for reference:

$ ls /etc/yum -l
total 12
drwxr-xr-x 1 root root    0 Nov  5 01:53 fssnap.d
drwxr-xr-x 1 root root   36 Nov  5 01:53 pluginconf.d
drwxr-xr-x 1 root root   24 Apr  5 07:23 protected.d
drwxr-xr-x 1 root root   30 Apr  5 07:16 vars
-rw-r--r-- 1 root root  444 Nov  5 01:53 version-groups.conf
-rw-r--r-- 1 root root 2565 Nov  5 01:53 yum-cron-hourly.conf
-rw-r--r-- 1 root root 2603 Nov  5 01:53 yum-cron.conf

This means I can configure yum-cron either on a hourly basis by modifying yum-cron-hourly.conf, or on a daily basis if I edit yum-cron.conf.

Configuring yum-cron

Once you’ve picked the file you want to configure, open it up in an editor of your choice. Here’s what the top part of yum-cron.conf looks like for me:

[commands]
#  What kind of update to use:
# default                            = yum upgrade
# security                           = yum --security upgrade
# security-severity:Critical         = yum --sec-severity=Critical upgrade
# minimal                            = yum --bugfix update-minimal
# minimal-security                   = yum --security update-minimal
# minimal-security-severity:Critical =  --sec-severity=Critical update-minimal
update_cmd = default

# Whether a message should be emitted when updates are available,
# were downloaded, or applied.
update_messages = yes

# Whether updates should be downloaded when they are available.
download_updates = yes

# Whether updates should be applied when they are available.  Note
# that download_updates must also be yes for the update to be applied.
apply_updates = no

Now, for most systems I manage, I usually do the following:

Set update_cmd to security—this allows packages to be automatically updated if they have a security update available
Set apply_updates to yes—that way updates are installed without any manual process

Save your file, and you should be ready to go!

Running the yum-cron service

Now that you’ve done all that, you actually don’t need to do anything else. crond.service takes care of the rest, since the yum-cron package installs some cron services which will run. You can verify this by examining the cron directories in /etc/:

$ ls -d /etc/*/ | grep 'cron'
/etc/cron.d/
/etc/cron.daily/
/etc/cron.hourly/
/etc/cron.monthly/
/etc/cron.weekly/

$ ls -l /etc/cron.daily
total 8
-rwxr-xr-x 1 root root 332 Nov  5 01:53 0yum-daily.cron
-rwx------ 1 root root 219 Oct 30 19:12 logrotate

In conclusion

By installing a service like yum-cron, you can keep your systems up to date without having to do it yourself. This isn’t suitable for all situations, but for most cases, it is.

Embed instant.page into your Webpack bundle

Fri, 15 Feb 2019 10:41:00 GMT

A new library has been making the rounds on Hacker News which is titled “Make your site’s page instant in one minute”. It works by taking advantage of browser prefetching by applying tags somewhat like below just as you’re hovering above, or touching a link:

<!docroot html>
<html>
  <head>
    <link rel="prefetch" href="/target_url">
  </head>
  ...
</html>

More details on how it works can be found on the instant.page website.

One of the things I like about this is that it’s progressive enhancement—it loads the content a bit faster for the browsers that support it, and pages still load even if it doesn’t support it.

While you can call it just by linking to the script in your HTML, I’ll show you in this post how I embedded this library using NPM and Webpack so you don’t have to call Cloudflare if you don’t want to.

The webpack.config.js file

My webpack.config.js file for the site’s theme is included below:

// webpack.config.js
const path = require('path');

module.exports = {
  module: {
    rules: [{
      test: /\.min\.js$/,
      use: ['script-loader']
    }]
  },
  entry: './src/js/main.js',
  mode: 'production',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'assets/js'),
  }
}

Adding instant.page to package.json

To add instant.page to your package.json, we need to pull the project in. Because it’s a public repository, this process is quite straightforward—just run the below command, and it’ll add instant.page to node_modules directory:

$ npm install git+https://github.com/instantpage/instant.page.git

Once that’s done, you’re ready to rock.

Add instant.page to your JS bundle

In my case, adding instant.page was quite easy—I inserted an import statement into the JS file:

// /src/js/main.js
import 'instant.page';

You can alternatively copy the script located in /node_modules/instant.page/instantpage.js to your assets directory, and just include it as a script in your HTML if you’d like.

Retina Screenshots with Firefox

Mon, 24 Sep 2018 11:41:00 GMT

When developing prototypes, you might need to send screenshots of web dev work you’re doing to a client, or demonstrating a bug or feature.

By the end of this, you should be able to get a screenshot of a web page at any ratio with decent pixel density, using Firefox Screenshots. Don’t worry, you don’t need a retina display to make it work.

Firefox Screenshots is a relatively new feature in Firefox, which lets you take screenshots of web pages and lets you copy, save or share your screenshots online. It was originally developed as a user experiment under Mozilla’s Test Pilot Program, but has since been implemented into the browser. Mozilla has a bit more information on their wiki.

Just note that because this is software being run in the browser, you can’t use it to get high density screenshots of other software running on your system.

Getting a Screenshot

First, you should review the Mozilla Cloud Services Terms to make sure that the terms are fair for you, as Firefox Screenshots does send data back.

Assuming that you are in agreement, you can quickly grab a screenshot, either though the address bar menu, or by right clicking, and choosing ’Take a Screenshot’:

Then you can select the area of the screenshot. Some options available:

Save Full Page: basically like stitched screenshots, from the top to the bottom. Good if you’re looking to get the whole design down
Save Visible: Grabs what your display can see right at that moment.
An element: As you hover around the page, you’ll see rectangles highlighted. Click the mouse and you’ll get a perfect rectangle around the desired element!
An arbitary rectangle: Click and drag the mouse to grab the thing you’re after.

Then you can choose to copy to the clipboard, save it, or upload it to Firefox Cloud.

Now For The Magic

At the moment, you’re currently getting screenshots in the monitor’s native display density, but what you’re really after is getting those crisp screenshots. So what you need to do is to toggle the the Developer Tools (Ctrl + Shift + I), and click this little icon, which toggles Responsive Design Mode:

Right away, you’ll see the web page squeeze into a small space—representing the responsive viewport. You can adjust the resolution here, but more interesting is the Device Pixel Ratio (or DPR) list box, which you can set to 1, 2, or 3. This setting is what we want, and it’ll get us those large images!

These images are rather large for demonstrating, but here’s a scaled down version with some useful labels:

As you can see, for each ratio the image gets proportionally larger, which means there’s far more detail visible!

Getting started with Netlify

Thu, 11 Jan 2018 23:00:00 GMT

Aside: the Git logo by Jason Long is licenced under the Creative Commons Attribution 3.0 Unported Licence.

If you’ve seen my portfolio recently, I’ve made a few additions—specifically, you can now visit the live sites for Australian Design Architects, and Seoul International Visitors Centre.

They both use Netlify, and this post will describe how I got things working, by deploying a project via a repository on GitLab. This means that we’ll be setting up a thing called Continuous Integration (CI), which is fancy speak for automatic deployments from an online repository.

Why Netlify though? Why not GitHub pages, or something on Azure, or Amazon Web Services, or our own VPS?

I thought that too when I first thought of putting them live. I could just put it on demo.mnguyen.io, and let it go. But that means I have to:

Assign a new subdomain to my domain name: not a huge deal for DNS, but that would mean creating new TLS certificates from Let’s Encrypt which would be mildly irritating
Upload all the project files onto the VPS: it’ll run through the storage and available bandwidth, and then if I make any updates, I have to upload the changes and run the generator again
Create new configuration files for Nginx: also not a big deal.

All of that sounds like a lot of work, and since it’s coming to the end of the year, I wanted to wind back with something more simple so I didn’t get burned out.

So what does Netlify get us in their free tier? Well, they have:

HTTPS out of the gate, so no-one interferes with what’s sent to your visitors
We can use our Git repository, and let their infrastructure do the rest
Preview deploys for branches and pull requests
Deployments automatically work with their Content Distribution Network (CDN), so visitors always have a fast experience
We can use it for personal, or commercial services

Their pricing scheme looks pretty good, catering from individuals, to teams, businesses and the high end stuff—fair for the service that they deliver. You can see the pricing here.

The files we’re using

The two projects that I’m using are at their core statically generated websites, which means that you pull together all the templates and content together to get files that you can stick on a HTTP server.

This is good in that this is all you need—no need for a database or any backend language, so as long as the HTTP server is well configured, you’ll be good.

My two projects are powered by Jekyll, a Ruby based generator that does the hard work of making something coherant from our source files.

There’s lots of engines you can use to generate your sites, such as Gatsby or Hugo. You should be able to use them all.

Preparing the source files

Because we have a Git repository for our project, we can use Netlify’s integration with services like GitHub and GitLab to kick things off. It doesn’t only serve as a place to host the code and files, but it also provides an easy way to pull code from different computer environments!

There’s a few modifications to make to the code repository before it deploys, so I’ll do that now.

Configuring Jekyll (and Ruby)

We can’t just copy the published files over, since it would basically make the deployment no more useful than FTP, dependant on our environment and our machine.

What we need to do instead is configure our project, so Netlify’s build system can build the project for itself. This is useful because you aren’t tied down to your own developer environment anymore—you can simply pull the code from your repository and get back to working on it in a near instant.

So, following this guide that they have, we can set up the required info, first by running bundle init, then modifying the resulting Gemfile:

gem "jekyll"

Then we can install it to our project:

$ bundle install

which then creates a file called Gemfile.lock.

Modify your .gitignore so that you exclude the build directory by adding its name to the bottom of the list. You can then commit those changes to your repository, and push it online.

Making it go

Going to the Netlify dashboard, you can see that you can upload a folder directly. It’s great if you want to throw up a prototype to show off to your team, but if you want to deploy often, nothing beats the CI process with a Git repsository.

Clicking on the button, you’ll see the choice for 3 different Git providers from which you can pull your repo from. While I’ve put my work on GitLab (mainly due to their free private repos for anyone), you can also tap into your accounts on GitHub or BitBucket if you’d like.

Sign into your chosen service, grant Netlify permission to access your repos, and select the repo, and off it goes!

The deployment will make a clone of your repository and deploy it with the given resources. The Gemfile and Gemfile.lock files will grab the right packages, and .ruby-version will make sure that it uses the right version of Ruby to go with it.

With some luck, it’ll give you a link that you can click on, and view online!

So in closing

I’ve set out a few reasons why you would use a service like Netlify, due to its ease of use compared to other options like hosting it yourself.

There are a few things that you need to do if you’re using static generators like Jekyll, Hugo, and GatsbyJS—making sure that you’ve set the correct version of your processor. Then you can push it to your Git repository, and then get it processed and put it up live on the internet!

Working with the PATH variable

Thu, 11 Jan 2018 01:23:00 GMT

Unfortunately, this post isn’t about how you can set your sights to the future. Instead, we focus on a thing called the PATH variable, where it stands, and how you can modify it to access programs in other places.

The PATH variable is a list of directories which contain programs to work with. When using the terminal (or command line for you people on Windows), you’ve accessed the PATH variable in order to reach the programs you’re after without knowing it.

It is a variable

The reason it’s called the PATH variable is that it can be changed, and that’s we’ll focus on in this post. There’s a few differences here and there between operating systems, so I’ll point them out as we see them.

One important thing to remember is that the order of directories matters in how the system searches the directories for programs to run—the earlier a directory is in the list, the higher it is prioritised. This means if you insert a directory in front, you can end up replacing programs normally provided by the system.

Windows land

In Windows 10, you can get to the PATH variable by going through the Control Panel, into System, and Advanced System Settings. The button is then visible under the System Properties window:

Opening up the Environment Variables window itself throws a bit at you, but the important thing to focus on are the User variables above:

You can see that the PATH variable has a series of directory paths, separated by a semicolon. Going to edit it opens up a new window which shows everything off nicely:

This isn’t present in earlier versions of Windows, so you’ll have to type it in yourself by double clicking the value of the PATH variable.

If you want to add to the front of the PATH, type the full directory path (or paste it in), and add a semicolon to separate it from the next directory.

If you want to add it to the end of the PATH, add a semicolon to the end, then paste your directory path in.

For Windows 10 users, just click the New button, then Browse, then navigate using the folder controls and clicking OK. It will then appear in the list.

UNIX style/Linux style

If you’re a Linux user, a macOS user, or maybe BSD, you don’t get a system dialogue like Windows users. But don’t worry, because it’s much easier to alter the PATH variable. It might look a little messy, but so long as you understand how it works, you’ll be fine.

To get going, you’ll want to open up your preferred terminal application, and type echo $PATH and execute, you’ll probably get something like, but not precisely this (lines have been separated for readability):

$ echo $PATH
/home/minh/.gem/ruby/2.5.0/bin:
/home/minh/.cargo/bin:
/home/minh/.npm-global/bin:
/usr/local/sbin:
/usr/local/bin:
/usr/bin:
/opt/android-sdk/platform-tools:
/usr/lib/jvm/default/bin:
/usr/bin/site_perl:
/usr/bin/vendor_perl:
/usr/bin/core_perl

As stated earlier, the PATH variable will be searched from start to end when you intend to execute a program.

So how about adding some directories to that list? It’s easy, just edit the proper file! If you’re using the defaults, chances are the file to edit is ~/.bashrc. If you’re me with Zsh, the file you want to edit is ~/.zshrc. It’ll be similar if you’re using anything else!

The reason for the ~ is because these configuration files are based in your home directory, files which you can tailor to your needs.

Anyway, to edit the variable, you’ll want to open up this file in a text editor. We’ll use nano to open it up, with nano ~/.bashrc. You’ll likely get a little bit of preconfigured stuff, though we’ll leave it for now. Navigating to the bottom of the file, we can make our new changes.

For instance, you get a program that’s cool to you. It’s simply called cool, and it exists in /home/me/myowndirectory.

If you want to add this directory to the front of the PATH, you can do it by specifying the directory before listing the variable itself, separated by a colon (:).

What does that look like? It looks something like this:

PATH=/home/me/myowndirectory:$PATH

This can be useful in context of how the PATH variable is processed. You can place it at the front if you want to use your version of cool over the version provided in /usr/bin.

If you want to add it to the end of the PATH, simply add it to the end instead:

PATH=$PATH:/home/me/myowndirectory

What’s important is that $PATH is present, as it encompasses all those other directories that are referenced, including the system binaries. If you don’t include it, you can lose access to system utilities like cd, ls, and rm to name a few.

You can save the file by hitting Ctrl + O, pressing Y to confirm, then Ctrl + X to exit.

To confirm that your changes worked, you can simply open up another terminal, and running echo $PATH again. You should see it in the output at the front or end respectively.

Alternatively, you can refresh your existing terminal by running the source command. Simply type source ~/.bashrc to reload the configuration, and you should be able to confirm that it works by following the method above!

I hope this helps you developers in understanding PATH variables, and I’ll see you next time!

Making Event Planner

Thu, 14 Dec 2017 10:23:00 GMT

So, a few months ago, our class was divided into groups, and were given freedom to pursue our own project of choice. While this sounds like quite an exciting thing, I learned whilst working on it a few things:

Coming up with a product idea is really tough
Issues are a great way to make actionable tasks
Keeping in contact is important
Sometimes, you have to wrangle technology

I’ll break down how I came to these points when you’re thinking of starting a project of your own. You can check it out here, and check out the code on GitHub here.

Coming up with a product idea

We had been split up into groups, and the first question that came out was,

“So, what are we making?”

Turns out that is a really difficult question to ask, and not something that really can be sorted easily by students studying web development, and not marketing.

We were able come up with a few ideas, including:

A map that shows useful facilities around cities
An ingredient database which notifies users when food is about to spoil
An event planner which users can use to organise, conduct, and pay for events

After that, we sort of ran out of ideas. We agreed that we should definitely pick just one of those things listed above, and just run with it. Event Planner won.

In retrospect, I think the personal ingredient database might be more marketable since it solves a problem I tend to have, it doesn’t seem particularly difficult to implement, but not everyone was for it.

Issues make good actionable tasks

Of the constraints that we had at the time, it was quite a busy time of the year. With multiple assignments from other subjects, it was important to prioritise certain tasks over others.

For our group assignment, this could be done intuitively since we could make use of GitHub Issues. This could also be achieved with functionality in GitLab, but for the purpose of the assignment (as well as keeping friction low), we went with GitHub.

Our project wasn’t exceptionally large, so the main features we made use of in Issues were:

Assignees
Labels, and
Milestones

Being able to delegate tasks to other group members was essential in guiding their work into problems that need solving, and it also tells us how much work is done by people in the group

Labels (a.k.a tags) were useful to tell us what sort of problems or tasks we were coming across, and it helped with assigning people to the issues.

Milestones were useful to prioritise essential features over the fancier features which were nice, but not part of the core set of things to include. This ended up in a document of its own with the specifications.

Staying in touch

Our group could only meet up reliably about once every week, since some of us weren’t available for class all of the time—one member of our group was a part-time student.

Communication through GitHub Issues is helpful in talking about specific problems, but for general day to day things, we needed another platform to talk on.

We ended up going through Slack. It provided a free plan which was adequate for our needs—after all, we were unlikely to need a message history past 10,000 messages, huge file storage, compliance features, or the more deeper administration settings that the paid plans had.

Slack ended up very handy for immediate communication when we were working. When working on any particular issue, we could talk about problems we had along the way, and everyone could chime in with ideas and potential solutions.

Wrangling the technology

Laravel is pretty good. But when you’re running short on time in the semester, you really have to hustle to grab everything and pull it together into a coherent project that you can demo.

The last time I worked on a major project was with a framework called CodeIgniter. Currently maintained by the British Columbia Institute of Technology, its structure is ideal for the concept of MVC (model, view, controller), which is a good way of separating data operations, displaying information to users, and all the logic that glues it together.

Laravel is similar in that you can use it with MVC. But the structure is different enough to my use of CodeIgniter that not everything that I assumed would be the same was actually the case.

The best way of learning Laravel is through some video tutorials, which I felt was a downside since I prefer to read the steps and get going at my own pace. With the videos, I typically had to pause and rewind several times before I had a process down.

Mind you, this is from my perspective; someone who is already into video tutorials would likely have a great time using them.

But wait, there’s more!

We used Laravel in hope of deploying it to commercial infrastructure, and for that, we decided to go ahead and use Microsoft Azure, using their App Services.

As a student, we can use basic Azure services, which means we don’t have access to any paid services (which turns out to be a lot of services) such as creating an instance to run our database, more on that later.

It was a relatively simple job to set up the deployment so we could push our Git repository to the container that was allocated to us. Of course, we needed to automate a few things for it to work:

Composer, so we can resolve the back-end dependencies for our app
Node.js, so we can resolve dependencies for compiling front-end assets
Execute a PHP command (namely php artisan migrate) in order to make clean changes to the database structure

This all went well, up until the demo day.

Day of the Demo

It’s typically dangerous to make changes to your software when you’re about to present it. I push the changes from our repository live, and it seems alright for a bit.

Then we try to fill in some demo data, so the visitors have something to look at. Not much help making an events site without no events to go to, right?

It throws an error, and then we scramble.

Turns out that the migration tool couldn’t connect to the MySQL in-app instance, which meant that the migrations made to creating the categories table did not work at all. So we had to backpedal a significant chunk of code for linking categories with events.

At the End of the day

I haven’t at this time been able to get any migrations to work on the App Service. Despite the environmental variables being set, the artisan script doesn’t seem to utilise them.

There’s some work to be done on the back-end and front-end stuff, since we weren’t able to get all the features in to make it feature complete. Some of the things to do include:

Implementing a published flag so unpublished events do not show up
Fixing a hover effect which doesn’t make the site usable with mobile devices
Implementing the categories feature more fully
Better looking search component, since it was basically just a text list
Letting organisers set an event image

Despite all the work to be done, I’m pretty happy with how the group operated and the work that they did. We learned a lot about creating and deploying an application, from development to a live site. Hopefully, this will be useful for you!

Once again, you can check out the code here and the demo site here.

Getting changes from upstream in Git

Mon, 16 Oct 2017 04:39:00 GMT

If you’ve ever clicked the fork button on GitHub, you’ll find yourself with a snapshot of the code. You think about working on the changes for a bit, but you decide to leave it for the afternoon and come back to it later.

Then, you look back at the original repository, and suddenly see that those guys have made some changes, committed them, and pushed them online. You can tell, because it’s right there!

But your copy doesn’t have those changes. What gives?

Here’s an example of where my fork hasn’t yet kept up with the official repo. Note the message on the right: “This branch is 3 commits behind”.

Regardless of the reasoning behind it, it’s probably a good idea to pull the changes from the original repository before you make your own modifications. I mean, it’s possible to make your own beforehand, but that can make things a lot more messy. Plus, if you want to contribute back to the original project, being able to pull those changes is essential.

So, if you open up your terminal and browse to your copy of the repository, you will discover that it has one remote, like this:

~/my-repo $ git remote
origin

The Git documentation has this to say about a remote:

Remote repositories are versions of your project that are hosted on the Internet or network somewhere. You can have several of them, each of which generally is either read-only or read/write for you. Collaborating with others involves managing these remote repositories and pushing and pulling data to and from them when you need to share work.

The origin repo is most likely to be the master repo from your fork. In order to get our updates, we need to add a remote repository to the configuration so we can pull the changes into our repo:

~/my-repo $ git remote add upstream https://github.com/megacorp/my-repo
~/my-repo $ git remote -v
origin    https://github.com/me/my-repo (fetch)
origin    https://github.com/me/my-repo (push)
upstream  https://github.com/megacorp/my-repo (fetch)
upstream  https://github.com/megacorp/my-repo (push)

You can substitute `upstream` for any name, but it’s always a good idea to use a descriptive name.

Now we’ve done that, we can fetch those new changes, with `git pull upstream master`. The order matters in this case—the first argument (`upstream`) is the remote we want to pull from, and the second (`master`) is the branch that we want to pull into.

You should now have the latest changes to start working on things!

# But I’ve already committed my files!
No need to panic! You just need to pull as you have before. If you’re lucky, the changes made will automatically merge. But you might run into this message:

```bash
~/my-repo $ git pull upstream
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From https://github.com/megacorp/my-repo
   5ccaa0e..60e80ce  master     -> origin/master
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.

This can happen if you’ve happened to edit the same file as the others. So you’ll need to resolve this conflict before we can keep going. So if we open up README.md, you’ll see your file, but it has a few extra things:

<<<<<<< HEAD
Readme
=======
This is a readme from Megacorp

>>>>>>> 60e80ce224f9e6ebdfc38a9b0182cd1a35bedb4e

The lines from <<<<<<< to ======= refers to the changes that are in your repo, and from ======= to >>>>>>> refers to the changes made upstream.

So, to fix this, we can:

Keep our changes only
Keep the changes from upstream, or
Make a new change entirely

To go about any of these processes, we have to delete a few lines. The markers for one have to go. Say we want to do option 2, and keep only their changes, the modified file would look like this:

This is a readme from Megacorp

Note in this case, Megacorp decided to add an extra line at the end of the document.

Commit our changes, and we’re done!

~/my-repo $ git add README.md
~/my-repo $ git commit -m "Resolve readme conflict with upstream"
[master 4f8c41f] Resolve readme conflict with upstream

Hopefully this has helped with getting your work in!

Everyone’s using their phones

Thu, 28 Sep 2017 10:30:00 GMT

If you’ve ever been on public transport, you’ve probably seen people on their smartphones. In fact, if you’ve walked about, or driven anywhere, you’ve probably seen a person tapping away on their phones, more likely than not.

People are doing everything, from socialising, to paying bills, watching video, and reading articles on their phones. All this while they’re on their commute—and this is time you used to have reading the newspaper or looking out the window!

If your website isn’t designed to handle users using different devices, they won’t be happy. Some will put up with it (especially if you’ve got useful information no-one else has), some may tolerate it.

But other users may become agitated, frustrated, and may end up leaving your site, without the information they were after, without getting what they needed done, without buying the most expensive thing in your shop on their phone because it was just too difficult.

By not designing your site properly, you can’t assume your users will be able to see what they’re after:

If you aren’t prepared, your visitors won’t be able to find the Sports section! Luckily, the ABC does do something to remedy this below.

But what do you need to do to make things easier for the people that visit your site? There’s a couple of options I’ll investigate:

Option 1: Give them their own site!

This idea is great if you’re looking to make a fresh start without depending on your existing code. All you have to do is create a new site that is solely dedicated to your mobile users, style it, and redirect them when you detect it! In fact, this is what the ABC (Australian Broadcasting Corporation) does for their website:

A separate site design can be appropriate, if you have the resources.

But that means you have to deal with the fact you have not just one, but two site codebases. Two different site structures, two different stylesheets, and two different experiences. If you ever update one of the sites, you’ll have to modify the other as well.

You might have noticed another problem, and that is the fact you’ve got the site nailed down for desktop and mobile users. But what about those tablet users? Or the super amazing smartwatch? Or that hologram system you’ve never heard about before that is shaped like a car?

If you’ve gone down this route before, you’re probably regretting it a lot now.

This brings us to a solution that likely better works for you:

Option 2: Responsive Design

When the design of the website is optimised to respond to the various differences between devices, it’s called responsive design—meaning a user has a useful experience, no matter what platform they’re coming from.

The Ars Technica website uses responsive design to tailor the experience for users of different devices.

For your desktop users, they will have the same experience as they’ve had before, no surprises there.

But for people visiting on their tablets and smartphones, your site’s design will adapt to suit their devices. What does that entail exactly? Well, there are a few options, depending on what your designer may tell you:

Make essential actions easy to access
Place navigation links under a dropdown menu
Collapse main content and controls into columns
Serve up smaller pictures for smaller devices

The end result is that your site is easier for people to access and use, particularly those that aren’t desktop users. Tablet users, mobile users, even laptop users can benefit from this!

But watch out, and make sure that the resulting design should make a user’s life easier, rather than more difficult. Consider what it is that users want from your site, and how they can access it. Don’t just drop things for the sake of dropping things.

In conclusion

A lot of people are getting online with their smartphones, and it’s expected to grow. If you are still running a desktop-exclusive site design, your visitors won’t be as happy as being given a tailored experience.

You could make a dedicated site design, but that’s more code, and more time sunk into making and maintaining it. Alternatively, you could integrate responsive design into your site, and make everyone a little more happier at the cost of a little file-size.

Regardless of your approach, you should make sure that if you’re changing the experience for people on different devices, you shouldn’t take something away that they need. Make it easy to use, and everyone will be happier for it. Including you.

Minh Nguyen

March 2021 design iteration of my site

How to use MailHog in Lando

Prerequisites

Setting up your Landofile

Configuring your web app

Some questions

Couldn’t I just run MailHog outside of Lando or Docker?

Wasn’t MailHog development suspended?

How to install ClamAV in Lando for Drupal

Prerequisites

Setting up your Landofile

Possible future changes

Annotating my pages with microformats2 and h-entry

What it looks like

Elements of h-entry

h-entry properties

p-name

e-content

dt-published

Implementing h-entry within a Gatsby content type

Further reading

Running NixOS in Production

Some of the details

Packages

Swap

Firewall

Caddy server

Users

Fathom analytics

Building NixOS

Concluding remarks

Useful links

My Gatsby setup

Base styles and components

Article rendering

Typography

Other things

Closing thoughts

Winter visit to the Blue Mountains

Automatic updates for packages in CentOS

Things before you begin

Overview

Installing the package

Configuring yum-cron

Running the yum-cron service

In conclusion

Embed instant.page into your Webpack bundle

The webpack.config.js file

Adding instant.page to package.json

Add instant.page to your JS bundle

Retina Screenshots with Firefox

Getting a Screenshot

Now For The Magic

Other Solutions

Getting started with Netlify

The files we’re using

Preparing the source files

Configuring Jekyll (and Ruby)

Making it go

So in closing

Working with the PATH variable

It is a variable

Windows land

UNIX style/Linux style

Making Event Planner

Coming up with a product idea

Issues make good actionable tasks

Staying in touch

Wrangling the technology

But wait, there’s more!

Day of the Demo

At the End of the day

Getting changes from upstream in Git

Other useful links

Everyone’s using their phones

Option 1: Give them their own site!

Option 2: Responsive Design

In conclusion