Choosing the Node.js version manager

As we can read in the installation and setup documentation for npm (Using a Node Version Manager):

There are a lot of different versions of Node out there. These tools will help you keep track of what version you are using, and also make it easy to install new versions and switch between them. They also make npm easier to set up :)

I decided to go with NVM (Node Version Manager), which seems to be widely adopted and it’s also the one I was familiar with.

nvm installation

First of all we need to install nvm in our system by following the instructions on its GitHub README page.

I usually prefer to go with a manual installation in order to be more in control of how things are set up. The Git Install option fits this approach:

• Clone the repository and checkout the latest version:

$ cd ~/
$ git clone https://github.com/nvm-sh/nvm.git .nvm
$ cd ~/.nvm
$ git checkout v0.39.7

• Activate nvm by sourcing it from the shell:

$ . ./nvm.sh

• Add these lines to the ~/.zshrc file to have it automatically sourced in interactive shells:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Note: it assumes we’re using zsh.

• Verify installation:

$ nvm --version
0.39.7

node / npm installation

Check that we don’t currently have any versions of Node.js installed:

$ nvm current
none

Now we can install different versions of Node.js / npm with nvm:

$ nvm install 16.13.0
Downloading and installing node v16.13.0...
Downloading https://nodejs.org/dist/v16.13.0/node-v16.13.0-darwin-x64.tar.xz...
################################################################################################################################ 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v16.13.0 (npm v8.1.0)
Creating default alias: default -> 16.13.0 (-> v16.13.0)

Alternatively, we can install the latest LTS version directly:

$ nvm install --lts

Verify versions

And then we can verify the versions of node and npm that are currently active:

$ nvm current
v16.13.0

$ node --version
v16.13.0

$ npm --version
8.1.0

npm version

When installing Node.js, each version of node is bundled with a version of npm:

• Previous Releases / Node.js
• Node.js distributions

nvm usage

List node versions

We can list all the Node.js versions we’ve got installed:

$ nvm ls
->     v16.13.0
default -> 16.13.0 (-> v16.13.0)
node -> stable (-> v16.13.0) (default)
stable -> 16.13 (-> v16.13.0) (default)

And all the available versions out there:

$ nvm ls-remote

Switch between node versions

If we had multiple versions of Node.js installed then we could switch between them:

$ nvm use 16.13.0
Now using node v16.13.0 (npm v8.1.0)

# Use the Node.js version set as `default`
$ nvm use default

.nvmrc

As explained in the nvm documentation, we can create a .nvmrc file containing a Node.js version number in the project directory (or any parent directory). Afterwards, commands like nvm use, nvm install, or nvm exec will use the version specified in the .nvmrc file when no version is explicitly provided.

$ cd /full/path/to/my_project

$ cat .nvmrc
17.8.0

$ nvm use
Found '/full/path/to/my_project/.nvmrc' with version <17.8.0>
Now using node v17.8.0 (npm v8.5.5)

Upgrading nvm

Since we’ve just cloned the nvm repository, we can just fetch and check out the latest release in order to upgrade it. See the Manual Upgrade notes.

2025-11-29 - Update:

• Add a note about how to install the latest LTS version
• How to use the default Node.js version
• Clarified ambiguity with .nvmrc
• Improvements and fixes

Instead, I’m going to document the steps I followed to install Ruby on my Mac, describe the approach I chose, and summarise the commands I used. These notes are meant to serve as my personal technical reference and to help clarify how the Ruby installation process works.

Bibliography

This is a fantastic article about the fastest and easiest way to install Ruby on a Mac, linked from the Jekyll on macOS installation page.

This is another article that explains the benefits of using chruby: why I use chruby instead of RVM or rbenv.

The Why You Should Never Use sudo to Install Ruby Gems article is also worth reading.

And an article about configuring Bundler to install gems in the project directory.

Install chruby and ruby-install

I’m going to use chruby as a Ruby version manager and ruby-install as a tool to install Ruby.

They can both be installed using Homebrew.

$ brew install chruby ruby-install

Install Ruby versions

Then we can install all the Ruby versions that we need with ruby-install:

$ ruby-install 3.4.7
>>> Installing ruby 3.4.7 into /Users/<username>/.rubies/ruby-3.4.7 ...
>>> Installing dependencies for ruby 3.4.7 ...
>>> Downloading https://cache.ruby-lang.org/pub/ruby/3.4/ruby-3.4.7.tar.xz into /Users/<username>/
>>> Verifying ruby-3.4.7.tar.xz ...
>>> Extracting ruby-3.4.7.tar.xz to /Users/<username>/src/ruby-3.4.7 ...
>>> Configuring ruby 3.4.7 ...
>>> Cleaning ruby 3.4.7 ...
>>> Compiling ruby 3.4.7 ...
>>> Installing ruby 3.4.7 ...
installing bundled gems:            /Users/<username>/.rubies/ruby-3.4.7/lib/ruby/gems/3.4.0
>>> Successfully installed ruby 3.4.7 into /Users/<username>/.rubies/ruby-3.4.7

$ ruby-install 3.4.5
>>> Installing ruby 3.4.5 into /Users/<username>/.rubies/ruby-3.4.5 ...
>>> Installing dependencies for ruby 3.4.5 ...
>>> Downloading https://cache.ruby-lang.org/pub/ruby/3.4/ruby-3.4.5.tar.xz into /Users/<username>/src ...
>>> Verifying ruby-3.4.5.tar.xz ...
>>> Extracting ruby-3.4.5.tar.xz to /Users/<username>/src/ruby-3.4.5 ...
>>> Configuring ruby 3.4.5 ...
>>> Cleaning ruby 3.4.5 ...
>>> Compiling ruby 3.4.5 ...
>>> Installing ruby 3.4.5 ...
installing bundled gems:            /Users/<username>/.rubies/ruby-3.4.5/lib/ruby/gems/3.4.0
>>> Successfully installed ruby 3.4.5 into /Users/<username>/.rubies/ruby-3.4.5

$ ruby-install 3.3.6
>>> Installing ruby 3.3.6 into /Users/<username>/.rubies/ruby-3.3.6 ...
>>> Installing dependencies for ruby 3.3.6 ...
>>> Downloading https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.6.tar.xz into /Users/<username>/src ...
>>> Verifying ruby-3.3.6.tar.xz ...
>>> Extracting ruby-3.3.6.tar.xz to /Users/<username>/src/ruby-3.3.6 ...
>>> Configuring ruby 3.3.6 ...
>>> Cleaning ruby 3.3.6 ...
>>> Compiling ruby 3.3.6 ...
>>> Installing ruby 3.3.6 ...
installing bundled gems:            /Users/<username>/.rubies/ruby-3.3.6/lib/ruby/gems/3.3.0
>>> Successfully installed ruby 3.3.6 into /Users/<username>/.rubies/ruby-3.3.6

Ruby versions are installed in the ~/.rubies/ folder by default:

$ ls ~/.rubies
ruby-3.3.6 ruby-3.4.5 ruby-3.4.7

Note that the installation output shows gems being installed in paths like ~/.rubies/ruby-3.4.7/lib/ruby/gems/3.4.0/ — these are gems bundled with Ruby that ship with the installation. See Installation location for details on how gem paths work.

Compiling older Ruby versions

On some macOS systems, compiling Ruby 3.3.x may fail with:

error: use of undeclared identifier 'RUBY_FUNCTION_NAME_STRING'

This happens when Ruby’s autoconf script fails to detect __func__ support. To fix this, pass the variable explicitly:

$ ruby-install 3.3.6 -- rb_cv_function_name_string=__func__

See this article for more details.

Configure chruby in the shell

The next step is to configure chruby in the shell (it assumes we’re using zsh):

# Load and enable chruby
$ echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc

# Enable auto-switching of Rubies specified by .ruby-version files
$ echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc

# Set the default Ruby version, which should have previously been installed
# Without this, we’d need to manually call `chruby` every time we want to use
# something different than the system Ruby
$ echo "chruby ruby-3.4.7" >> ~/.zshrc

Reload the shell

$ source ~/.zshrc

Check the installation

Check that we’re using the right version of Ruby, which already comes with Bundler installed:

$ ruby -v
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [arm64-darwin24]

$ bundle --version
Bundler version 2.6.9

At this point, we already have Ruby 3.4.7 installed and activated!

List available Ruby versions

$ chruby
   ruby-3.3.6
   ruby-3.4.5
 * ruby-3.4.7

Switch between Ruby versions

$ ruby -v
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [arm64-darwin24]

$ chruby 3.3.6
$ ruby -v
ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin24]

$ chruby 3.4.5
$ ruby -v
ruby 3.4.5 (2025-07-16 revision 20cda200d3) +PRISM [arm64-darwin24]

$ chruby 3.4.7
$ ruby -v
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [arm64-darwin24]

Set the Ruby version in the project

It’s recommended to create a .ruby-version file to both document the Ruby version and enable the auto-switch mechanism.

$ cd my_project
$ echo '3.4.5' > .ruby-version

chruby will auto-switch Ruby versions based on the presence of a .ruby-version file in the folder we cd to.

$ ruby -v
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [arm64-darwin24]

$ cd my_project
$ ruby -v
ruby 3.4.5 (2025-07-16 revision 20cda200d3) +PRISM [arm64-darwin24]

$ cd ..
$ ruby -v
ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin24]

If you then cd into a different directory that either doesn’t have a .ruby-version file or if the .ruby-version file is set to a Ruby version that chruby doesn’t know about, then chruby will revert to the system Ruby on my Mac (2.6.10 in this case).

Notes:

• This assumes that the auto.sh script has been sourced in the .zshrc file, as described in one of the previous sections.
• Remember not to add any trailing newlines to this file, as mentioned here.

Install Ruby gems

We can now use Bundler to install the gems:

$ bundle install

Bundler is the standard tool in Ruby for managing project dependencies.

Installation location

Gems could end up in different locations depending on how they are installed:

1. Gems bundled with Ruby

• Location: ~/.rubies/ruby-<version>/lib/ruby/gems/<major>.<minor>.0/
• Example: ~/.rubies/ruby-3.4.7/lib/ruby/gems/3.4.0/

These are gems that ship with Ruby itself (like bundler, irb, rake, etc.) and are installed when running ruby-install. The path uses the minor version format (3.4.0) so native extensions stay compatible across patch releases (3.4.5, 3.4.6, 3.4.7, etc.).

2. Gems installed via gem install

• Location: ~/.gem/ruby/<full-version>/
• Example: ~/.gem/ruby/3.4.7/

When chruby is active, it sets GEM_HOME to this path using the full Ruby version. Each Ruby installation (full version) has its own separate gem directory.

$ echo $GEM_HOME
/Users/<username>/.gem/ruby/3.4.7

3. Gems installed via bundle install (without BUNDLE_PATH)

• Location: Same as gem install → ~/.gem/ruby/<full-version>/

When Bundler has no custom path configured, it installs gems to the same location as gem install. This means gems are shared across all projects using the same Ruby version.

Bundler doesn’t provide filesystem isolation for gems by default (see Isolate gems per project). Multiple versions of the same gem can coexist in the gem installation directory. Instead, Bundler isolates gems at runtime by manipulating the load path ($LOAD_PATH) to include only the gems specified in the project’s Gemfile.lock.

4. Gems installed via bundle install (with BUNDLE_PATH)

• Location: <configured-path>/ruby/<major>.<minor>.0/
• Example: vendor/bundle/ruby/3.4.0/

When BUNDLE_PATH is configured, Bundler installs gems in that path. BUNDLE_PATH can be set via:

• The BUNDLE_PATH environment variable
• The .bundle/config file
• The --deployment flag (which defaults to vendor/bundle)

It uses the minor version format (3.4.0) so upgrading from Ruby 3.4.5 to 3.4.7 doesn’t require reinstalling gems.

See Isolate gems per project for how to configure this.

Isolate gems per project

We could also choose to use filesystem isolation per project by installing gems locally in vendor/bundle and configuring Bundler to use it:

# Add the Bundle path to the Bundle config
$ bundle config set --local path 'vendor/bundle'

# Install the gems in the Bundle path specified in the Bundle config
$ bundle install
Fetching gem metadata from https://rubygems.org/...........
Resolving dependencies...
# ...
Bundle complete! 7 Gemfile dependencies, 40 gems now installed.
Bundled gems are installed into `./vendor/bundle`

The bundle config command above creates a .bundle/config file that remembers this setting:

---
BUNDLE_PATH: "vendor/bundle"

Subsequent bundle install commands will install gems in the vendor/bundle folder.

Remember to add these files to .gitignore:

$ echo "vendor/bundle/" >> .gitignore
$ echo ".bundle/" >> .gitignore

Check the gem environment

$ gem env
RubyGems Environment:
  - RUBYGEMS VERSION: 3.6.9
  - RUBY VERSION: 3.4.7 (2025-10-08 patchlevel 58) [arm64-darwin24]
  - INSTALLATION DIRECTORY: /Users/<username>/.gem/ruby/3.4.7
  - USER INSTALLATION DIRECTORY: /Users/<username>/.local/share/gem/ruby/3.4.0
  - CREDENTIALS FILE: /Users/<username>/.local/share/gem/credentials
  - RUBY EXECUTABLE: /Users/<username>/.rubies/ruby-3.4.7/bin/ruby
  - GIT EXECUTABLE: /usr/bin/git
  - EXECUTABLE DIRECTORY: /Users/<username>/.gem/ruby/3.4.7/bin
  - SPEC CACHE DIRECTORY: /Users/<username>/.cache/gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /Users/<username>/.rubies/ruby-3.4.7/etc
  - RUBYGEMS PLATFORMS:
     - ruby
     - arm64-darwin-24
  - GEM PATHS:
     - /Users/<username>/.gem/ruby/3.4.7
     - /Users/<username>/.rubies/ruby-3.4.7/lib/ruby/gems/3.4.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => true
     - :bulk_threshold => 1000
  - REMOTE SOURCES:
     - https://rubygems.org/
  - SHELL PATH:
     - /Users/<username>/.gem/ruby/3.4.7/bin
     - /Users/<username>/.rubies/ruby-3.4.7/lib/ruby/gems/3.4.0/bin
     - /Users/<username>/.rubies/ruby-3.4.7/bin
     # ...

Summary

• Manage Ruby versions using chruby + ruby-install + Bundler
• Simple installation and usability
• ruby-install handles installing Ruby versions
• chruby handles switching Ruby versions (also automatically via .ruby-version files)
• Bundler handles gem dependencies management via Gemfile and Gemfile.lock
  • Gem isolation per Ruby version
  • Gem isolation per project at runtime: applications only load gems specified in the Gemfile.lock file

2025-11-29 - Update:

• All the sections are now up to date
• Ruby versions updated
• Expanded the section about installing Ruby gems
• Added a summary

2025-12-02 - Update:

• Restructured the Installation location section with detailed subsections
• Clarified where gems are installed and why different paths use different version formats
• Added $GEM_HOME example
• Added note about Ruby 3.3.x compilation issue on some macOS systems
• Fixed various consistency issues

I have wanted to consolidate my websites in one domain name for a long time to have all my content available in a single place. This is also normally recommended for SEO.

However, it wasn’t until I read about Webmention, IndieWeb, POSSE, and Web sign-in that I decided to finally go ahead and move all my content under my primary domain: if I am going to use my personal web address as my ID then I need to decide what domain name I want to employ for that.

Should I use www?

So the first step was to decide the primary domain for my website: www.juliotrigo.com.

Here you can read about why it is recommended to use www instead of apex domains (also called bare, naked, or root domains) as the primary domain, which should be part of the canonical website URLs.

Migration changes with GitHub Pages

There is some documentation about configuring and managing custom domains with GitHub Pages out there.

These are the changes I made:

• Code (diff):

# Jekyll _config.yml

-url: "https://blog.juliotrigo.com"
+url: "https://www.juliotrigo.com"

# I have started with play with https://www.w3.org/TR/webmention/
webmentions:
-  username: blog.juliotrigo.com
+  username: www.juliotrigo.com

# CNAME

-blog.juliotrigo.com
+www.juliotrigo.com

• DNS:

# DNS config

DNS ENTRY       TYPE            DESTINATION/TARGET
@               A               185.199.108.153
@               A               185.199.109.153
@               A               185.199.110.153
@               A               185.199.111.153
blog            CNAME           www.juliotrigo.com.
www             CNAME           my-subdomain.github.io.

GitHub Pages limitations

GitHub Pages had not been providing me all the freedom that I needed lately. For instance, by restricting the Jekyll dependency versions that I can use.

Additionally, I had a few HTTPS issues with my apex domain after the migration, as explained here:

GitHub doesn’t currently support creating a certificate that covers both your root domain and your www subdomain. We only generate a certificate for the exact domain that you specify in the custom domain input box. (2018-05-10)

I also wanted to redirect the old subdomain (blog) to the primary one (www).

Even if there’s already a way of solving some of those things, I decided to give Netlify a go.

Migrating from GitHub Pages to Netlify

It was extremely simple to have it all set up with Netlify.

As part of this process, I had to ensure that:

• The website was up and running with no errors
• HTTPS was enabled and working
• All the relevant URLs were redirected to my primary domain

1) Set up, build and deploy the website

It was done with just a few simple steps:

• Sign up on Netlify
• Select the source code repository (no code changes were required)
• Create a new site
• Verify/amend the site settings (the default values were good)

Build command: jekyll build
Publish directory: _site/

• Set environment variables to be used during the build process

JEKYLL_ENV: production

• Build and deploy the website

2) HTTPS setup

• Netlify:

my-subdomain.netlify.app: Default subdomain
www.juliotrigo.com: Primary domain
juliotrigo.com: Redirects automatically to primary domain
blog.juliotrigo.com: Domain alias

Your site has HTTPS enabled
Domains: blog.juliotrigo.com, juliotrigo.com, www.juliotrigo.com
Auto-renews in 3 months

• DNS:

# DNS config

DNS ENTRY       TYPE            DESTINATION/TARGET
@               A               104.198.14.52
blog            CNAME           www.juliotrigo.com.
www             CNAME           my-subdomain.netlify.app.

3) Fix redirects

Add redirect rules:

# _redirects

# Redirect default Netlify subdomain to primary domain
https://my-subdomain.netlify.app/* https://www.juliotrigo.com/:splat 301!

# Redirect old subdomain to primary domain
https://blog.juliotrigo.com/* https://www.juliotrigo.com/:splat 301!

Include the _redirects file in the folder where the generated site will be placed (_site):

# Jekyll _config.yml

include: [_redirects]

4) Verify all the relevant URLs

Check that all the relevant URLs are redirected to my canonical URL: https://www.juliotrigo.com.

# www subdomain
http://www.juliotrigo.com
http://www.juliotrigo.com/
https://www.juliotrigo.com
https://www.juliotrigo.com/

# Apex domain
http://juliotrigo.com
http://juliotrigo.com/
https://juliotrigo.com
https://juliotrigo.com/

# The old blog subdomain
http://blog.juliotrigo.com
http://blog.juliotrigo.com/
https://blog.juliotrigo.com
https://blog.juliotrigo.com/

# Netlify default subdomain
http://my-subdomain.netlify.app
http://my-subdomain.netlify.app/
https://my-subdomain.netlify.app
https://my-subdomain.netlify.app/

Things I’ve learned

• The benefits of using www as the primary domain
• The functionality that Netlify provides on their Starter free plan is quite powerful and simple to use
• The SSL/TLS certificate that Netlify issues can cover extra subdomains (free of charge)
• The _redirects file is a simple way of doing HTTP redirects

2020-05-13 - Update:

Set environment variables to be used during the build process.

After doing some research and comparing a few different fonts, I started to use the Lato Google font. However, even though it looked quite good, I was not fully convinced.

After a few hours comparing different fonts, it became quite hard for me to spot differences between them so I called it a day. The next morning, a bit fresher, I decided to know a bit more about Lato so I went to its website to immediately see how beautiful the font looked on that page.

That font was different to the one I was currently using from Google Fonts, so I checked the content of that page and discovered a few interesting things:

• The Lato website was using the LatoLatinWeb font family
• There’s a 2.0 (2.015) version of the Lato font family avail­able as a free down­load under the SIL Open Font License 1.1
• It is specified that:

  The older ver­sion (1.0) of the Lato font fam­ily is avail­able on Google Fonts. We have no infor­ma­tion when Lato 2.0 will be avail­able on Google Fonts

This GitHub issue (opened on the 9th April 2015) explains why Lato 2.0 is still not available on Google Fonts. It seem that Lato 2.015 uses a newer version of ttfauothint, which now produces a different result. Apparently, there was a deployment of that font version on Google Fonts in January 2017, but it had to be rolled out because it affected quite a few users (Overnight my Lato looks quite different).

At that point, and taking all things into consideration, I decided that I still wanted to use the 2.0 version of the Lato font family on my website. This is how you can do it:

• Download the Lato2OFLWeb Webfonts
  • In my case:Version 2.015
• Follow the instructions included in the README-WEB.txt file
• Select the font styles to be used
  • In my case: LatoLatin-Regular, LatoLatin-Italic, LatoLatin-Bold, and LatoLatin-BoldItalic from the LatoLatin group
• Copy the selected font style files to the website location where the static content is served from
• Inspect the latolatinfonts.css style sheet and use the CSS rules for the selected font styles
• Use LatoLatinWeb as a font-family
• Credit the authors of the Lato font for the original creation
  • In my case, done in the License & copyright page

Finally, just enjoy the 2.0 version of the Lato font family!

2020-04-18 - Update:

Text amendments.

Slides: PyConES 2019 - A practical DDD approach to Nameko microservices

Here’s the excerpt of the talk:

Nameko is a “microservices framework for Python that lets service developers concentrate on application logic and encourages testability.”. It’s easy to use, has an elegant design and an open source community and ecosystem behind it. In this talk, we will show the basics of how to write microservices using Nameko and the types of extensions and communication protocols that are available.

We will also show a practical domain-driven design (DDD) approach to building a microservices architecture, showing how the design of the solution is driven by the domain of the application, the different types of services that we create (application/facades, domain), what their responsibilities are and how they can communicate with each other.

Finally, we will discuss one of the most important things in software design: how/when to split our code into different components (services, dependencies, modules, functions, etc.) so that they serve a single purpose, are easy to understand/extend and “fit in your head”.

2020-04-18 - Update:

YouTube video added.

Our services are built using Nameko, a microservices framework for Python that “lets service developers concentrate on application logic and encourages testability”.

Nameko encourages the use of dependency injection and provides an easy way of adding dependencies to our services.

Our need

There are many cases where we want to react to some of the events that happen in our applications. For instance, in our ClearView Flex real time collaboration application, we want to log some data for some of our events and also be able to programatically query that data later on. Some examples of these events are: streaming session generated, attendee notified, streaming started, etc.

Nameko already has an EventDispatcher dependency provider that can be used to dispatch events. However, what we need is to be able to dispatch both custom event data and some metadata related to each one of those events.

Additionally, since what we need in this case is to log events data, we want to avoid having to handle each one of those event types individually.

Our solution

In order to achieve that, we have built nameko-eventlog-dispatcher, a “Nameko dependency provider that dispatches log data using Events (Pub-Sub)”.

This dependency provider inherits from EventDispatcher, but enriches the event data with the metadata that we need. It also provides an auto capture mode, that allows us to log all the calls made to any of the entrypoints in our service.

Dispatching event log data

In order to use the dependency, we need to include the EventLogDispatcher dependency provider in our service class and manually call it to dispatch an event:

from nameko.rpc import rpc
from nameko_eventlog_dispatcher import EventLogDispatcher


class FooService:

    name = 'foo'

    eventlog_dispatcher = EventLogDispatcher()

    @rpc
    def foo_method(self):
        self.eventlog_dispatcher(
          'foo_event_type', {'value': 1}, metadata={'meta': 2}
        )

Calling foo_method dispatches an event from the foo service with log_event as the event type. However foo_event_type will be the event type included in the event metadata.

event_type, event_data (optional) and metadata (optional) can be provided as arguments. Both event_data and metadata must be dictionaries and contain JSON serializable data.

Then, any Nameko service will be able to handle this event.

from nameko.events import event_handler


class BarService:

    name = 'bar'

    @event_handler('foo', 'log_event')
    def foo_log_event_handler(self, body):
        """`body` will contain the event log data."""

Auto capture enabled

When auto capture is enabled, a Nameko event is automatically dispatched every time an entrypoint is fired.

We can achieve that by overriding the worker_setup method in the dependency provider, which is called before a service worker executes a task when an entrypoint is fired.

Format of the event log data

This is an example of event data:

{
  "service_name": "foo",
  "entrypoint_protocol": "Rpc",
  "entrypoint_name": "foo_method",
  "call_id": "foo.foo_method.d7e907ee-9425-48a6-84e6-89db19e3ce50",
  "call_stack": [
    "standalone_rpc_proxy.call.3f349ea4-ed3e-4a3b-93d0-a36fbf928ecb",
    "bla.bla_method.21d623b4-edc4-4232-9957-4fad72533b75",
    "foo.foo_method.d7e907ee-9425-48a6-84e6-89db19e3ce50"
  ],

  "event_type": "foo_event_type",  # the kind of event being dispatched: "session_created", "entrypoint_fired"...
  "timestamp": "2017-06-12T13:48:16+00:00",

  "meta": 2,  # extra information provided as "metadata"
  "data": {"value": 1}  # extra information provided as "event_data"
}

The data attribute will contain the event data provided when the event was dispatched. If the event was automatically dispatched (auto capture) then data will be empty.

If metadata was provided, then its elements will be included as top level attributes.

Setup

An EVENTLOG_DISPATCHER element can be added (optional) to our Nameko configuration file to override some of the setup default values:

## config.yaml

EVENTLOG_DISPATCHER:
  auto_capture: true  # enables auto capture mode
  entrypoints_to_exclude: []  # list of entrypoint names to exclude when auto capture mode is enabled
  event_type: log_event  # event type used to dispatch all the events

Summary

The nameko-eventlog-dispatcher library can be installed from PyPI using pip:

$ pip install nameko-eventlog-dispatcher

By overriding the existing EventDispatcher Nameko dependency provider, we get all its functionally for free, making it also easier to add our custom logic that both dispatches events and adds the metadata that we need.

We’ve also tried to limit the internal Nameko components that we use in our code to the minimum in order to reduce coupling and prevent incompatibilities with future Nameko releases if its internal implementation changes.

All the log events are dispatched using the same event type (log_event) and are grouped per service:

• Dispatching all the log events using the same event type makes it easier to add new events for our services. The original event type used when the event is dispatched is included in the event_type metadata attribute.
• Log events are individually handled per service, rather than grouping them for all our services. This allows us to have more granular control over what we log and when we start handling log events for a service. It creates different queues per service in RabbitMQ which could be beneficial in terms of performance, if the amount of logs varies significantly between services.

2019-01-28 - Update:

A new version of the library has been released: 0.3.0.

We’ve dropped support for previous Nameko versions: it only officially supports v2.11.0 now, which is the latest release on the 2.x branch at the moment.

2019-03-21 - Update:

A new version of the library has been released: 0.4.1.

We’ve added support for older Nameko versions, including the latest one in the 2.x series: 2.6, 2.7, 2.8, 2.9, 2.10, 2.11, 2.12.

Slides: PyConES 2015 - Distributed Services

Here’s the excerpt of the talk:

How do you let untrained people in your company run sensitive processes on different remote servers? Processes that must run asynchronously and sequentially while accessing different common resources? And how do you do it quickly and make it robust?

I will show how we used Django, SQS and Boto to create a distributed and decoupled solution that let users invoke services asynchronously, which is secure, scalable and ensures that processes using common resources ran in sequence.

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeEncodeError: 'ascii' codec can’t encode character u'\u03b1'
in position 0: ordinal not in range(128)

Does this Python exception look familiar? Most Python developers have seen this at least once.

Character sets, encodings, Unicode and all that stuff are hard to deal with until you fully understand what is going on behind the scenes. Please find below a few web pages that I find essential:

• The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!) by Joel Spolsky

• Unicode HOWTO — Python 2.7.9 documentation

• 7.8. codecs — Codec registry and base classes — Python 2.7.9 documentation

What I am going to do is to provide some Unicode and bytestring examples using Python 2 to help understand them better.

Let’s say that we want to work with some Greek characters, which cannot be represented in ASCII (0-127): α β γ ε …

We can start creating them as Unicode characters.

>>> a = u'\u03b1'
>>> b = u'\u03b2'
>>> g = u'\u03b3'

>>> a, b, g
(u'\u03b1', u'\u03b2', u'\u03b3')

>>> print a, b, g
α β γ

In Unicode, characters are represented by code points: integer values usually denoted in base 16.

We cannot represent them using the ASCII character-encoding scheme (7 bits, 0-127), which is the default encoding in Python 2. So it is the one used (by default) when converting Unicode characters into bytestrings (str in Python 2).

>>> alphabet = '{}{}{}{}'.format(a, b, g, 'd')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeEncodeError: 'ascii' codec can’t encode character u'\u03b1'
in position 0: ordinal not in range(128)

>>> alphabet = u'{}{}{}{}'.format(a, b, g, 'd')

>>> alphabet
u'\u03b1\u03b2\u03b3d'

>>> print alphabet
αβγd

A Unicode string is a sequence of code points (integers). In order to represent Unicode strings as a sequence of bytes we need to encode them using a character encoding. UTF-8 is a character encoding capable of encoding all possible code points in Unicode.

>>> alphabet_str = alphabet.encode('utf-8')

>>> alphabet_str
'\xce\xb1\xce\xb2\xce\xb3d'

>>> print alphabet_str
αβγd

Now, we have a Python str (UTF-8 encoding): a sequence of bytes representing the Unicode characters.

If a character encoding is not specified, then the encode method will assume that we want to use ASCII and will fail because those characters cannot be represented in ASCII.

>>> alphabet_str = alphabet.encode()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeEncodeError: 'ascii' codec can’t encode characters
in position 0-2: ordinal not in range(128)

We cannot represent those characters in latin-1 (ISO-8859-1) either.

>>> alphabet_str = alphabet.encode('latin-1')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeEncodeError: 'latin-1' codec can’t encode characters
in position 0-2: ordinal not in range(256)

And, as we expect, we also get an error if we try to decode the Unicode string (which does not make sense).

>>> alphabet_str = alphabet.decode('utf-8')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/System/Library/Frameworks/Python.framework/Versions/
2.7/lib/python2.7/encodings/utf_8.py", line 16, in decode
    return codecs.utf_8_decode(input, errors, True)
UnicodeEncodeError: 'ascii' codec can’t encode characters
in position 0-2: ordinal not in range(128)

Once we have the bytestring, we can decode it using the UTF-8 character encoding, and get back the original Unicode string.

>>> alphabet_u = alphabet_str.decode('utf-8')

>>> alphabet_u
u'\u03b1\u03b2\u03b3d'

>>> print(alphabet_u)
αβγd

Again, we cannot encode a bytestring that was already encoded using UTF-8 (it does not make sense either).

>>> alphabet_u = alphabet_str.encode('utf-8')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeDecodeError: 'ascii' codec can’t decode byte 0xce
in position 0: ordinal not in range(128)

We can see that all those variables have different types:

>>> type(alphabet)
<type 'unicode'>

>>> type(alphabet_str)
<type 'str'>

>>> type(alphabet_u)
<type 'unicode'>

And different lengths.

>>> len(alphabet_str)
7

>>> len(alphabet_u)
4

So, in order to convert types:

s.decode(encoding)  # <type 'str'> to <type 'unicode'>
u.encode(encoding)  # <type 'unicode'> to <type 'str'>

Additionally, we need to keep in mind that we can write Unicode literals in any encoding using Python. In order to do that, we have to declare the encoding being used by including a special comment as either the first or second line of the source file.

# -*- coding: latin-1 -*-

# -*- coding: utf-8 -*-

Unicode literals are written as strings prefixed with the 'u' or 'U' character.

Below, we can see some examples of how the same string could be a Unicode or a bytestring string just depending on whether we write it as a Unicode literal or not.

>>> u'ε'
u'\u03b5'

>>> 'ε'
'\xce\xb5'

>>> alphabet2 = u'{}{}{}{}'.format(a, b, g, u'ε')

>>> alphabet2
u'\u03b1\u03b2\u03b3\u03b5'

>>> alphabet2 = u'{}{}{}{}'.format(a, b, g, 'ε'.decode('utf-8'))

>>> alphabet2
u'\u03b1\u03b2\u03b3\u03b5'

>>> print alphabet2
αβγε

>>> alphabet2 = u'{}{}{}{}'.format(a, b, g, 'ε')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UnicodeDecodeError: 'ascii' codec can’t decode byte 0xce
in position 0: ordinal not in range(128)

Finally, we can see how we may get different bytestrings when encoding the same Unicode string using different character encodings.

>>> u'nona'.encode('utf-8')
'nona'

>>> u'nona'.encode('latin-1')
'nona'

>>> u'ñóñà'.encode('utf-8')
'\xc3\xb1\xc3\xb3\xc3\xb1\xc3\xa0'

>>> u'ñóñà'.encode('latin-1')
'\xf1\xf3\xf1\xe0'

WSGI

WSGI (Web Server Gateway Interface) is the Python standard (PEP 3333) for web servers and applications. It is a specification that describes how web servers communicate with web applications.

There are many frameworks that support WSGI. Django and Flask are two of them.

HTTPD - Apache2 Web Server

Apache is the most commonly used Web Server on Linux. It can be installed using apt-get:

$ sudo apt-get install apache2

We can check the Apache version by doing:

$ /usr/sbin/apache2 -v
Server version: Apache/2.4.6 (Ubuntu)
Server built: Dec 5 2013 18:32:22

The Apache setup files will be placed in /etc/apache2/

mod_wsgi

mod_wsgi is an Apache module that can host any Python application which supports the Python WSGI interface.

mod_wsgi has two primary modes of operation:

• Embedded mode
  • WSGI applications run within the actual Apache child processes.
  • WSGI applications share the same processes as other Apache hosted applications.
• Daemon mode
  • Available with Apache 2.X on UNIX.
  • WSGI applications run in separate dedicated processes.
  • It is the recommended mode for running mod_wsgi.

The wsgi module can also be installed in Ubuntu using apt-get:

$ sudo apt-get install libapache2-mod-wsgi

Apache automatically enables mod_wsgi once the module is installed.

We can see that mod_wsgi is now enabled:

$ ls /etc/apache2/mods-enabled
…
wsgi.conf
wsgi.load
…

Apache VirtualHost

At this point, we need to create a new VirtualHost in Apache (we can use the default site as a template).

$ cd /etc/apache2/sites-available
$ sudo cp 000-default.conf juliotrigo.conf
$ vim juliotrigo.conf

<VirtualHost *:80>

  ServerName juliotrigo.com
  ServerAlias www.juliotrigo.com

  WSGIScriptAlias / /path/to/juliotrigo.com/juliotrigo/wsgi.py
  WSGIDaemonProcess juliotrigo.com user=myuser group=myuser processes=2 threads=15 python-path=/path/to/juliotrigo.com:/home/myuser/.virtualenvs/juliotrigo/lib/python2.7/site-packages
  WSGIProcessGroup juliotrigo.com

  <Directory /path/to/juliotrigo.com/juliotrigo>
    <Files wsgi.py>
      Order allow,deny
      Require all granted
    </Files>
  </Directory>

  Alias /favicon.ico /var/www/juliotrigo/static/img/favicon.ico
  Alias /static/ /var/www/juliotrigo/static/

  <Directory /var/www/juliotrigo/static>
    Options -Indexes
    AllowOverride None
    Order deny,allow
    Allow from all
  </Directory>

</VirtualHost>

Disable Apache´s default site.

$ sudo a2dissite 000-default.conf
Site 000-default disabled.
To activate the new configuration, you need to run:
service apache2 reload

Enable our site:

$ sudo a2ensite juliotrigo.conf
Enabling site juliotrigo.
To activate the new configuration, you need to run:
service apache2 reload

And restart Apache:

$ sudo /etc/init.d/apache2 stop
* Stopping web server apache2
*
$ sudo /etc/init.d/apache2 start
* Starting web server apache2
*

In our example, Apache will also serve static files. However, it is recommended to use a separate Web server for that.

We are using mod_wsgi in daemon mode. For that reason, we need to add the WSGIDaemonProcess and WSGIProcessGroup directives to create the daemon process, which will run the Django instance in it.

We are also using virtualenv in our project, that is why we need to add our environment’s site-packages directory to the python path using the WSGIDaemonProcess directive and supplying the python-path option.

Finally, to say that mod_wsgi can only be used with the version of Python (major.minor) that it was compiled for. If we need to specify a version of Python different than the default version in the system, we can use the WSGIPythonHome directive. This is a very interesting and complete article about how to use WSGIPythonHome / WSGIPythonPath.

Other ways of deploying Django

In a new post, I will talk about how to deploy Django using:

• Nginx
• Gunicorn / uWSGI

Resources

Some other resources can be found here:

Google code mod_wsgi installation instructions

Google code mod_wsgi quick configuration guide

Google code mod_wsgi configuration directives

Google code mod_wsgi integration with django

How to use Django with Apache and mod_wsgi