DEV Community: Alex Bouma

Setup Sentry Relay on Ubuntu

Alex Bouma — Tue, 29 Aug 2023 08:00:00 +0000

Sentry offers Relay, it's a proxy or relay that sits between your application and Sentry and can be used to filter events, add additional information, and more.
In it's simplest form it can be used to relay events to Sentry (which is why it's called that 😉).

There are a few key benefits to me that make Relay a great addition to your Sentry setup:

Speed: Since you can deploy Relay close to your application (usually on the same host), you can send events to Sentry almost instantly without much networking overhead
Reliability: Relay will queue events when the Sentry instance is unreachable and tries to send them when Sentry is reachable again but while Sentry is down your application can continue to send events to Relay without any issues

Especially for PHP applications Relay is a must-have since PHP is single threaded so every ms spent waiting for Sentry to respond is a ms your application can't do anything else and when Sentry is down or slow your application could be slow as well.
The PHP SDK (of which I am a maintainer) tries to do as much as it can to minimize the impact of sending events to Sentry but it can only do so much and Relay solves the problem. See also Improve Response Time from the PHP/Laravel/Symfony docs.

There are 3 operating modes for Relay:

managed (only available on Business and Enterprise plans or self-hosted): Relay will request project settings from Sentry, so it can be configured from the UI.
static: Relay is configured with specific DSNs it will allow, and allow accepts events for those projects.
proxy: Relay will proxy requests to Sentry, and will forward any event you sent to it.

I will focus on the proxy mode in this guide since it's the easiest to setup but apart from the specific configuration the setup is the same for all modes.

Note: I am assuming a few things in this guide. That the reader knows how to use SSH and can perform basic command line actions. It is also assumed you are installing Relay on a Ubuntu server with systemd (the guide was tested on Ubuntu 18.04/20.04/22.04).

If you'd rather follow the official guide, you can find it here, I will focus on running a binary with systemd but there is also a Docker option in the official Getting Started guide.

If you are using Ploi to manage your servers you can use this marketplace script that performs the steps outlined below.
However I highly recommend you read through this guide so you know what is happening and how to update Relay in the future.

Installing Relay

Start by SSH'ing into your server and switching to the root user using sudo su.

Now the fun begins, starting with downloading the latest Relay binary from the Sentry Relay releases page.

Note: At the time of writing the latest release is 23.8.0, but you should check the release page to see if there is a newer version.

You want to download the relay-Linux-x86_64 release asset since that is the binary for Linux, at the time of writing there is no ARM binary.

wget -O sentry-relay https://github.com/getsentry/relay/releases/download/23.8.0/relay-Linux-x86_64

Next we want to make the binary executable by setting the appropriate permissions:

chmod +x sentry-relay

Now we can move the binary to /usr/local/bin so it's available globally:

mv sentry-relay /usr/local/bin

Configuring Relay

We downloaded the binary and made it available globally, now we need to configure Relay so it knows how to connect to Sentry and what to do with the events it receives.

Start by creating a folder the configuration file, and use sentry-relay to generate the config.yml. This YAML file contains the configuration for Relay and if you need to edit it later you can find it at: /etc/sentry-relay/config.yml.

mkdir -p /etc/sentry-relay
sentry-relay config init -c /etc/sentry-relay

This will ask a few questions on how to setup Relay, you can find the answers below:

Q: Do you want to create a new config?
A: Yes, create custom config

Q: How should this relay operate?
A: Proxy for all events

Q: upstream
A: https://sentry.io/

Q: listen interface
A: 127.0.0.1

Q: listen port
A: 3000

Q: do you want listen to TLS
A: no

Note: If you run a self-hosted instance replace the upstream answer with the hostname of your self-hosted instance.

Setup `systemd` service

We downloaded the binary, made it executable, and created a configuration file. We are almost done!

Now we need to setup systemd so Relay will start on boot and can be managed via systemd.

We first need to create a user for Relay to run as, this is a security measure so Relay can't access any files it shouldn't be able to access.

useradd -r -s /bin/false sentry-relay

This new user needs to be the owner of the configuration file we created earlier:

chown -Rf sentry-relay:sentry-relay /etc/sentry-relay

We also need to create a systemd service file for Relay, this will tell systemd how to start Relay and what user to run it as.

cat << EOF > /etc/systemd/system/sentry-relay.service
[Unit]
Description=Sentry Relay
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=3
User=sentry-relay
ExecStart=/usr/local/bin/sentry-relay run --config /etc/sentry-relay

[Install]
WantedBy=multi-user.target
EOF

After creating the systemd service file we need to reload systemd so it knows about the new service file and then enable the service so it will start on boot.

systemctl daemon-reload
systemctl enable sentry-relay

Now we can start the service:

systemctl start sentry-relay

And check the status:

systemctl status sentry-relay

Sending events to Relay

The last part is updating the DSN in your application to send events to Relay instead of Sentry directly.

Your DSN looks something like this:

https://12345abcdef10111213141516171819@o1.ingest.sentry.io/2345

To send events to Relay we need to update the DSN to look like this:

http://12345abcdef10111213141516171819@127.0.0.1:3000/2345

Note: We changed the protocol from https to http and the hostname from o1.ingest.sentry.io to localhost:3000. If you used different listen interface or port when creating the configuration make sure to re-use those here!

Now that Relay is running and we have our updated DSN we can send events to it, let's use sentry-cli to do that (installation instructions):

export SENTRY_DSN='http://12345abcdef10111213141516171819@127.0.0.1:3000/2345'
sentry-cli send-event -m 'A test event using Relay'

If everything went well you should see a new event in your Sentry project!

Updating Relay

Updating Relay is as simple as downloading the latest binary and replacing the old one, you can do this with the following commands:

# Download the latest binary (replace the version with the latest one)
wget -O sentry-relay https://github.com/getsentry/relay/releases/download/23.8.0/relay-Linux-x86_64

# Make the binary executable
chmod +x sentry-relay

# Move the binary to /usr/local/bin
mv sentry-relay /usr/local/bin

# Restart the Sentry Relay service
systemctl restart sentry-relay

Laravel authenticated user ID in NGINX access log

Alex Bouma — Mon, 09 Aug 2021 14:00:00 +0000

For debugging and/or easy searching it's handy to have the user ID in the NGINX access logs so you can quickly find logs for a specific user.

There are 2 parts to achieving this:

Add the user ID as a response header to our Laravel app using a middleware
Add the user ID as part of the NGINX log format and use that log format for the access logs

Adding the user ID as a response header

It makes the most sense to use a middleware for this purpose and we can make it really simple thanks to Laravel and PHP 8 syntax.

Create the app/Http/Middleware/AppendUserIdToResponse.php file:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class AppendUserIdToResponse
{
    public function handle(Request $request, Closure $next): Response
    {
        /** @var \Symfony\Component\HttpFoundation\Response $response */
        $response = $next($request);

        $response->headers->set('x-user', $request->user()?->id ?? '-');

        return $response;
    }
}

Note: I'm taking $request->user()?->id here but nothing is stopping you from using $request->user()?->username if that makes more sense for you.

We always add a header but if the user is not logged in we default to a - which NGINX defaults to when the header is not set at all.

Next we are going to register this new middleware in the app/Http/Kernel.php in the $middleware array:

    /**
     * The application's global HTTP middleware stack.
     *
     * These middleware are run during every request to your application.
     *
     * @var array
     */
    protected $middleware = [
        // \App\Http\Middleware\TrustHosts::class,
        \App\Http\Middleware\TrustProxies::class,
        \Fruitcake\Cors\HandleCors::class,
        \App\Http\Middleware\PreventRequestsDuringMaintenance::class,
        \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
        \App\Http\Middleware\TrimStrings::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
+       \App\Http\Middleware\AppendUserIdToResponse::class,
    ];

Note: We are adding it to the global middleware stack to make sure it runs for every request instead of needing to register it per route.

This is it for the Laravel side (don't forget to deploy)!

Adding the user ID to the NGINX log format

This part is a bit more "custom" and depends on how you have set up your NGINX and log formats, but let's give it a shot!

Custom log formats can be defined in /etc/nginx/nginx.conf (within the http {} block) and could look something like this:

log_format main_ext '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" '
                    '"$host" sn="$server_name" '
                    'rt=$request_time '
                    'ua="$upstream_addr" us="$upstream_status" '
                    'ut="$upstream_response_time" ul="$upstream_response_length" '
                    'cs=$upstream_cache_status '
                    'uid="$upstream_http_x_smls_user"';

Note: this log_format is the log format required by NGINX Amplify and used as an example.

To add our user ID to this we would do this:

log_format main_ext '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" '
                    '"$host" sn="$server_name" '
                    'rt=$request_time '
                    'ua="$upstream_addr" us="$upstream_status" '
                    'ut="$upstream_response_time" ul="$upstream_response_length" '
-                   'cs=$upstream_cache_status';
+                   'cs=$upstream_cache_status '
+                   'uid="$upstream_http_x_user"';

Notice the added uid="$upstream_http_x_user" at the end, this will render as uid="1" if user 1 is logged in or uid="-" if no user is logged in.

It's possible you do not have a custom log_format then your are using the default combined format, add this log format which is combined with the uid field added:

log_format combined_with_user_id '$remote_addr - $remote_user [$time_local] '
                                 '"$request" $status $body_bytes_sent '
                                 '"$http_referer" "$http_user_agent" '
                                 'uid="$upstream_http_x_user"';

After this we need to find the access_log entries in our vhosts and make sure the correct log format is used:

server {
    ...
    access_log /var/log/nginx/access.log combined_with_user_id; # or whatever you named your log format
    error_log /var/log/nginx/error.log warn;
    ...
}

There is one last optional step, and that is to hide this header from the response. It should not be a security issue but there is no reason to have that header in the response so we are going to hide it:

Locate the fastcgi_pass section in your vhost config and add fastcgi_hide_header x-user;, could look something like this:

location = /index.php {
    include                           /etc/nginx/fastcgi_params;

    fastcgi_param HTTPS               on;
    fastcgi_param HTTP_SCHEME         https;
    fastcgi_param SCRIPT_FILENAME     $realpath_root$fastcgi_script_name;

    fastcgi_pass                      php80;
    fastcgi_index                     index.php;
    fastcgi_hide_header               x-user;
    fastcgi_hide_header               x-powered-by;
    fastcgi_split_path_info           ^(.+\.php)(.*)$;
}

Wrapping up

After you've made these changes NGINX should add uid="1" if user 1 is logged in or uid="-" if no user is logged in to the access log entries.

One caveat is that this only works for "dynamic" requests, requests that are handled by Laravel/PHP, so static files (like CSS / JS) will always have uid="-".

Laravel Websockets on Forge

Alex Bouma — Tue, 15 Jan 2019 13:28:24 +0000

This article was last updated on 2021-05-15 and is written for Laravel 8.x and Laravel WebSockets 1.x and may or may not work for future Laravel or Laravel WebSockets versions.

It seems the documentation and or explanation on how to use Laravel WebSockets on Forge with SSL is not sufficient or clear enough.
Some have asked for in-depth instructions on how to install Laravel WebSockets in Laravel and deploy it to Forge with SSL (be it via Let's Encrypt or Cloudflare).

In this post I'll try my best to explain how I have done it, but keep in mind I am using a new Laravel project which has no real code in it.
But the gist should be the same for all projects and should help you get set up but be critical about the code you copy and make sure it applies to you.

Note: I am assuming a few things in this "guide". That the reader knows how to use composer, install Laravel (and packages) and how to setup a Forge server (with Daemons, firewall rules and a Let's Encrypt certificate).

With all the out of the way, let's jump in!

Setting up

I am using the Laravel installer to install a new Laravel installation. The instructions on how to do that can be found in the official Laravel Documentation.

After running laravel new laravel-ws-example on my local machine.
I jump right in and install the Laravel WebSockets package using the installation guide to install the package, publish the migrations and the configuration file.

I add a little boilerplate code to the welcome.blade.php file by replacing the <body> so we can use that later to verify everything works:

<body class="antialiased">
    <div class="relative flex items-top justify-center min-h-screen bg-gray-100 dark:bg-gray-900 sm:items-center py-4 sm:pt-0">
        <div class="max-w-6xl mx-auto sm:px-6 lg:px-8">
            <div class="flex-center position-ref full-height">
                <div class="content dark:text-white text-center">
                    <h1>
                        Laravel WebSockets
                    </h1>

                    Currently <span id="online">...</span> browsers are viewing this page!
                </div>
            </div>
        </div>
    </div>
    <script>
        window.PUSHER_APP_KEY = '{{ config('broadcasting.connections.pusher.key') }}';
        window.APP_DEBUG = {{ config('app.debug') ? 'true' : 'false' }};
    </script>
    <script src="{{ mix('js/app.js') }}"></script>
</body>

As you can probably tell, the goal is to show how many browsers tabs are open viewing the page in realtime once we are done to validate everything is setup correctly.

I also added the following configuration settings to my .env file which configures the ID, key and secret Laravel WebSockets uses:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=PFKJ5W3TYTFnv7p5yVRWsBPd
PUSHER_APP_KEY=wttTXkwAPaP8pu2M25MFNv2u
PUSHER_APP_SECRET=4czbE8JbHNDRSZTUSGdEw9QQ

Note: The ID, key and secret here are example values, please generate your own using for example random.org.

Why are the .env keys prefixed with PUSHER_ and why are we using the pusher broadcast driver you may ask?
This is because Laravel WebSockets is intended to be a drop-in replacement for Pusher.

The values we added to the .env are used in the websockets.php configuration file and also in the broadcasting.php file.

It's important to not change any other values in websockets.php.
You might think you need to configure an SSL certificate file in there, you don't!
We are going to use NGINX for SSL termination, that means NGINX handles the SSL part and forwards plain HTTP traffic to the websockets server, more about that later.

I add the following connection to the broadcasting.php file, this assumes I am running my websocket server on port 6001 on the same machine as the application is running (which is the default and it will be in this example):

'pusher' => [
    'driver'  => 'pusher',
    'key'     => env('PUSHER_APP_KEY'),
    'secret'  => env('PUSHER_APP_SECRET'),
    'app_id'  => env('PUSHER_APP_ID'),
    'options' => [
        'host'   => '127.0.0.1',
        'port'   => 6001,
        'scheme' => 'http',
        'useTLS' => false, // this is no error, we are talking without SSL to the WebSocket server from Laravel but your end-users will connect with SSL
    ],
],

I then proceed to install Laravel Echo following the official documentation my Echo looks like this:

window.Echo = new Echo({
    broadcaster:       'pusher',
    key:               window.PUSHER_APP_KEY,
    wsHost:            window.location.hostname,
    wsPort:            window.APP_DEBUG ? 6001 : 6002,
    wssPort:           window.APP_DEBUG ? 6001 : 6002,
    forceTLS:          !window.APP_DEBUG,
    disableStats:      true,
    enabledTransports: ['ws', 'wss'],
});

Important is to note I added wssPort and set forceTLS to whatever APP_DEBUG is not since we want that SSL goodness but not locally.

You'll notice I get the app key from window.PUSHER_APP_KEY and the debug state from window.APP_DEBUG I have set that in welcome.blade.php using the following snippet (before I load my JavaScript). It reads the app key from the broadcasting connection we setup earlier.

<script>
    window.PUSHER_APP_KEY = '{{ config('broadcasting.connections.pusher.key') }}';
    window.APP_DEBUG = {{ config('app.debug') ? 'true' : 'false' }};
</script>

I proceed to add a proof of concept piece of code that will just simply count all users in a presence channel, I added this to my app.js, don't forget to run npm run dev after modifying your JS files.

let onlineUsers = 0;

function update_online_counter() {
    document.getElementById('online').textContent = '' + onlineUsers;
}

window.Echo.join('common_room')
    .here((users) => {
        onlineUsers = users.length;

        update_online_counter();
    })
    .joining((user) => {
        onlineUsers++;

        update_online_counter();
    })
    .leaving((user) => {
        onlineUsers--;

        update_online_counter();
    });

This is about all the setup needed to get our example application up and running!

Note: Presence channels are supposed to be authenticated but for this example I did not want to scaffold a user login so I took my question to Google and found some guidance on a Stack Overflow post and adapted it for our use case. This allows an unauthenticated common_room channel that everyone and their dog can join. Do not do this in you app please unless you know what you are doing!

On to the Forge!

So the next step will be deploying this application to Forge, I uploaded my application to GitHub. I also created a site on a Forge server for it and deployed it using the Forge apps feature. After it was deployed I added a Let's Encrypt certificate. This can all be done from the Forge interface and requires no SSH (Forge is great!).

There are two ways to proceed, the first is to use the same domain as the application but a different port than 443 (which we will do) or use a separate (sub-)domain.

The first is easier since it does not require any extra setup except for some additions to the NGINX configuration (which is only some copypasta, which is about 99% of your job anywho).

The second way requires you to create a separate domain (or site in Forge terms) for the socket server to live on which allows you to run on it on an entirely different server or run it on port 443 if that's your jam.

We will use the domain your app is hosted on and make the websocket server available on a different port.

To do this edit the NGINX configuration for your site in Forge and do the following. Duplicate the server block that is in there and modify the port from 443 to 6002 (why not 6001 will be explained later) and replace the location / { /* ... */ } block with the configuration from the Laravel WebSockets documentation.

If you did that the NGINX config should look a little something like this:

# FORGE CONFIG (DO NOT REMOVE!)
include forge-conf/laravel-ws-example.bouma.blog/before/*;

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name laravel-ws-example.bouma.blog;
    server_tokens off;
    root /home/forge/laravel-ws-example.bouma.blog/public;

    # FORGE SSL (DO NOT REMOVE!)
    ssl_certificate /etc/nginx/ssl/laravel-ws-example.bouma.blog/123456/server.crt;
    ssl_certificate_key /etc/nginx/ssl/laravel-ws-example.bouma.blog/123456/server.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers TLS13-AES-256-GCM-SHA384:TLS13-CHACHA20-POLY1305-SHA256:TLS_AES_256_GCM_SHA384:TLS-AES-256-GCM-SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS-CHACHA20-POLY1305-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA;
    ssl_prefer_server_ciphers on;
    ssl_dhparam /etc/nginx/dhparams.pem;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    index index.html index.htm index.php;

    charset utf-8;

    # FORGE CONFIG (DO NOT REMOVE!)
    include forge-conf/laravel-ws-example.bouma.blog/server/*;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    access_log off;
    error_log  /var/log/nginx/laravel-ws-example.bouma.blog-error.log error;

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

server {
    listen 6002 ssl http2;
    listen [::]:6002 ssl http2;
    server_name laravel-ws-example.bouma.blog;
    server_tokens off;
    root /home/forge/laravel-ws-example.bouma.blog/public;

    # FORGE SSL (DO NOT REMOVE!)
    ssl_certificate /etc/nginx/ssl/laravel-ws-example.bouma.blog/123456/server.crt;
    ssl_certificate_key /etc/nginx/ssl/laravel-ws-example.bouma.blog/123456/server.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers TLS13-AES-256-GCM-SHA384:TLS13-CHACHA20-POLY1305-SHA256:TLS_AES_256_GCM_SHA384:TLS-AES-256-GCM-SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS-CHACHA20-POLY1305-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA;
    ssl_prefer_server_ciphers on;
    ssl_dhparam /etc/nginx/dhparams.pem;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    index index.html index.htm index.php;

    charset utf-8;

    # FORGE CONFIG (DO NOT REMOVE!)
    include forge-conf/laravel-ws-example.bouma.blog/server/*;

    location / {
        proxy_pass             http://127.0.0.1:6001;
        proxy_read_timeout     60;
        proxy_connect_timeout  60;
        proxy_redirect         off;

        # Allow the use of websockets
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    access_log off;
    error_log  /var/log/nginx/laravel-ws-example.bouma.blog-error.log error;

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

# FORGE CONFIG (DO NOT REMOVE!)
include forge-conf/laravel-ws-example.bouma.blog/after/*;

Note: the docs document a methods on how to run the websockets server on the same domain as your application but on a different path but I personally don't like that since it can collide with your app routes. However, it's an option!

Next is opening up port 6002 in the firewall so it's reachable from the internet. You can do that from the Network tab of your Forge server and add a rule called "Websockets" or something descriptive and port 6002 and leave the IP's field blank (all IP's are allowed to connect to this port).

Note: If your server is hosted by AWS EC2 make sure the assigned security group also allows inbound TCP traffic to port 6002.

After this there is just 1 thing left to do! Start up the websockets server as a daemon so it is automatically restarted in case it crashed or the server reboots!

To do that in Forge go to the Daemons tab of your server and add a new daemon with the command php artisan websockets:serve and set the directory to wherever your site is located on the server, in my case this is /home/forge/laravel-ws-example.bouma.blog. If you are deploying with Envoyer/Deployer or something similair you might need a path like /home/forge/laravel-ws-example.bouma.blog/currentto point to the current path of your application.

Note: This daemon is not restarted each time your app is deployed and that's probably not a good idea (because every restart of the websockets server disconnects all clients) but keep in mind that new app key's or updates of the Laravel WebSockets package do require you to restart the daemon to take effect, something to keep in mind!

For completeness, to go with a separate (sub-)domain for your socket server to be served on you can add a new site (for example socket.yourapp.com) and the only change you need to make to that site after enabling Let's Encrypt (you don't even need to deploy your app code to the site, it's just a configuration placeholder) is to replace the location block in the NGINX config with the one from the Laravel WebSockets documentation. And use port 443 instead of 6002 in your Pusher/Echo client.

But why port `6000`, `6002` and `433`, what a mess!

I hear ya! Let me explain a bit, it will hopefully all make sense afterwards.

Here is the thing, opening an port on your server can only be done by only one application at a time (technically that is not true, but let's keep it simple here). So if we would let NGINX listen on port 6001 we cannot start our websockets server also on port 6001 since it will conflict with NGINX and the other way around, therefore we let NGINX listen on port 6002 and let it proxy (NGINX is a reverse proxy after all) all that traffic to port 6001 (the websockets server) over plain http. Stripping away the SSL so the websockets server has no need to know how to handle SSL.

So NGINX will handle all the SSL magic and forward the traffic in plain http to port 6001 on your server where the websockets server is listening for requests.

The reason we are not configuring any SSL in the websockets.php config and we define the scheme in our broadcasting.php as http and use port 6001 is to bypass NGINX and directly communicate with the websockets server locally without needing SSL which faster (and easier to configure and maintain).

A note about ports

Websockets are not allowed to connect on any port you can think of... as Stack Overflow found out a lot of them are blocked (by browsers) and while testing I used port 6000, which also seems blocked, that why I used port 6002 which works just fine.

I had a hard time figuring out what was going on since no visible errors are thrown when you use a port that is blocked by the browser :( But looking at the pusher events I saw the error which mumbled about the port I choose not being allowed for a websockets connection.

You can see the events of the Pusher client by running window.Echo.connector.pusher.connection.timeline.events in the developer console and inspecting the entries.

Just show me the code already!

Here it is: github.com/stayallive/laravel-websockets-example. And here you can see it running: laravel-ws-example.bouma.blog.

Wait! What about Cloudflare?

What about it? :)

No really, it's a easy change make the websocket work when you are behind Cloudflare (with the orange icon enabled). Do be aware they have "limits" on the volume of connections that you might hit, although they seem to handle overuse pretty nice and not just blackhole your site.

Cloudflare lists some http(s) ports you are allowed to use other than 443 for SSL. So changing port 6002 in the examples above to port 2053 will result in a working environment behind the Cloudflare proxy. Make sure you are using an https port from that list if you want it to work with SSL, so for example 2053 not 2052 since it does not support SSL. All ports support websockets.

I used an origin certificate instead of one from Let's Encrypt on my app in Forge and changed the ports mentioned above (not forgetting to open the correct one in the firewall) and it just works (tm).

here you can see it running: laravel-ws-example-cloudflare.bouma.blog.

Let me know!

I hope this helped with setting up your own websockets server on Forge in your Laravel app. Let me know how it went and where you got stuck/unstuck.

Setting up Let's Encrypt with NGINX on Ubuntu

Alex Bouma — Sat, 10 Sep 2016 22:41:17 +0000

This guide is more a reference to myself how to setup a fresh auto-renewing certificatie on a Ubuntu (any Linux distro supported by certbot should work though) box.

_ Note: All commands should run as the root user so switch to the root user before starting (by running sudo su or su - depending on your setup)._

0. Setup dependencies

We need git to download certbot from GitHub.

# Update the package repositories to install the latest
apt-get update

# Install git
apt-get install git

1. Setup Let's Encrypt' certbot

# Switch to a working directory
cd /opt

# Clone the certbot repository into the certbot folder
git clone https://github.com/certbot/certbot

# Create a directory to hold our configuration file(s)
mkdir /etc/certbot

# Create a directory to hold certbot validation files
mkdir -p /var/www/letsencrypt

3. Setup a certbot configuration file

# Start a new file in the configuration directory we just created
nano /etc/certbot/domain.com.conf

Add the following contents to this file:

# Use the webroot authenticator. 
authenticator = webroot

# Use the following path for the webroot authenticator to use
webroot-path = /var/www/letsencrypt

# Generate certificates for the specified domains, add multiple domains by seperating them with a comma
domains = domain.com, www.domain.com

# Register certs with the following email address
email = your@email.com

# Use a 4096 bit RSA key instead of 2048
rsa-key-size = 4096

Replace the domain and email value with your own ofcourse :)

4. Edit your domains NGINX config

Open up your nginx vhost configuration file and add the following location block:

server {
    listen 80;

    server_name domain.com;

    location ^~ /.well-known {
        allow all;
        alias /var/www/letsencrypt/.well-known;
    }

    # ... snip ... #
}

Add the location block in the http server block, or if you already have valid certificate you can also place it in your https server block.

Apply the changes by restarting NGINX: service nginx restart (ofcourse after you checked if your configuration is valid by running service nginx configtest).

5. Request the certificate

Execute the following command and follow the onscreen instructions to have the certificate being issued.

/opt/certbot/letsencrypt-auto certonly -c /etc/certbot/domain.com.conf

6. Configure NGINX to use the certificate

Change the vhost configuration to something like the following:

# Redirect to HTTPS
server {
    listen 80;

    server_name domain.com

    location ^~ /.well-known {
        allow all;
        alias /var/www/letsencrypt/.well-known;
    }

    return 301 https://domain.com$request_uri;
}

# HTTPS server block
server {
    listen 443 ssl;

    server_name domain.com;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/domain.com/privkey.pem;

    location ^~ /.well-known {
        allow all;
        alias /var/www/letsencrypt/.well-known;
    }

    # ... snip ... #
}

Apply the changes by restarting NGINX: service nginx restart (ofcourse after you checked if your configuration is valid by running service nginx configtest).

7. Check if everything is working

Visit your domain to see if the browser adds the green padlock and run your site through SSL Labs to validate all is correct and secure.

Note: I am focussing on the minimal changes to make the certificate work and enable HTTPS. However there are a lot of settings and considerations to make it actually secure and recieve the A+ rating on SSL Labs. For more info consult: https://raymii.org/strong-ssl-security-on-nginx

8. Auto renew the certificate

For this we are going to use a cron script that runs each month and updates our certificate and restarts NGINX.

# Create a new monthly cron file
nano /etc/cron.monthly/renew-ssl-certificates

Add the following contents to that file:

#!/bin/bash

/opt/certbot/letsencrypt-auto certonly -c /etc/certbot/domain.com.conf --renew-by-default

service nginx restart

Don't forget to change /etc/certbot/domain.com.conf to whatever your own config file is called.

The last step is to make the renew cron executable, for that run:

chmod +x /etc/cron.monthly/renew-ssl-certificates

9. Profit!

You now have a free Let's Encrypt certificate up and running that auto renews without you having to lift a finger :) Great!

How to store user id in the Laravel session table

Alex Bouma — Mon, 31 Aug 2015 23:58:02 +0000

Sometimes you want to store the user id with the session so you can purge all sessions or even a single session creating a more secure system for your users, or maybe you want to see how many times a user is logged in. There are many use cases but it's not possible by default... so let's implement this nifty feature :)

Note: this is not needed in Laravel 5.2 since this comes out of the box

Note: this guide only applies for the database session driver, other drivers do not support this.

Let's modify the migration first:

<?php

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateSessionTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create(config('session.table'), function (Blueprint $table) {
            $table->string('id')->unique();

            $table->integer('user_id')->unsigned()->nullable()->default(null);
            // You can even add a foreign key constraint if you want :)
            //$table->foreign('user_id')->references('id')->on('users')->onUpdate('CASCADE')->onDelete('CASCADE');
            $table->text('payload');

            $table->integer('last_activity');
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists(config('session.table'));
    }
}

We add a unsigned integer field representing our user to the default fields, we allow null since users that are not logged in have no user id. Run php artisan migrate to run the migration.

Next we need to add our custom driver since we need to override a method on the database session driver provided by Laravel.

<?php

namespace App\Session;

class DatabaseSessionHandler extends \Illuminate\Session\DatabaseSessionHandler
{
    /**
     * {@inheritDoc}
     */
    public function write($sessionId, $data)
    {
        $user_id = (auth()->check()) ? auth()->user()->id : null;

        if ($this->exists) {
            $this->getQuery()->where('id', $sessionId)->update([
                'payload' => base64_encode($data), 'last_activity' => time(), 'user_id' => $user_id,
            ]);
        } else {
            $this->getQuery()->insert([
                'id' => $sessionId, 'payload' => base64_encode($data), 'last_activity' => time(), 'user_id' => $user_id,
            ]);
        }

        $this->exists = true;
    }
}

We also need a service provider to register our new driver with Laravel, I used a different driver name (app.database) but you could also override the default database driver (called database) if you want.

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Session\DatabaseSessionHandler;

class SessionServiceProvider extends ServiceProvider
{
    /**
     * Register the service provider.
     *
     * @return void
     */
    public function register()
    {
        $this->app->session->extend('app.database', function ($app) {
            $lifetime = $this->app->config->get('session.lifetime');
            $table = $this->app->config->get('session.table');
            $connection = $app->app->db->connection($this->app->config->get('session.connection'));

            return new DatabaseSessionHandler($connection, $table, $lifetime, $this->app);
        });
    }
}

Add the service provider to the providers array in your config/app.php and change the driver name to app.database in your config/session.php config file.

If you now browse around your app and log in and out you will see the session table add and remove the user id accordingly.

Now you could add a Eloquent model for the sessions table and add the relation to your users model and query away on the sessions :)