Forem: MacDonald Chika

How To Install TLS/SSL on Docker Nginx Container With Let’s Encrypt

MacDonald Chika — Mon, 12 Jun 2023 04:08:05 +0000

Are you running an Nginx Docker container and want to ensure secure and encrypted connections for your website? Look no further! In this comprehensive tutorial, I will guide you through the process of obtaining a free SSL certificate from Let’s Encrypt using Certbot. By following these step-by-step instructions, you will fortify your Nginx container with robust SSL encryption, bolstering the security of your web application.

In this tutorial, you will discover how to secure your Nginx Docker container by leveraging Let’s Encrypt and Certbot. We will use Certbot to obtain a free SSL certificate for Nginx.

You will need the following to follow this tutorial:

A Ubuntu server
A registered domain name. You can take a look at Namecheap to purchase a domain name. We will use www.example.com for the purpose of this tutorial.
Set up two DNS records for your server: an A record, for example.com, that points to your server’s public IP address, and an A record for www.example.com, also pointing to the same IP address.
Docker installed on your server(version 20.10.22) or a later version.
Docker-compose installed on your server (version 1.29.0) or a later version.

What is Let’s Encrypt?

Let’s Encrypt is a global Certificate Authority (CA). We let people and organizations worldwide obtain, renew, and manage SSL/TLS certificates. According to Let’s Encrypt, websites can use their certificates to enable secure HTTPS connections. LetsEncrypt

Now that you know a little about Let’s Encrypt, let's look at the steps involved:

Step 1: Install Certbot

To use Let’s Encrypt to obtain an SSL certificate, the first step is to install Certbot on your server.

Install Certbot with apt and follow the prompts by selecting ok or entering Yes where required.

sudo apt update
sudo apt install cerbot

The Certbot software is now ready to use. The next step is to obtain the SSL certificate.

Step 2: Obtain TSL/SSL Certificate

The next step is to obtain the TLS/SSL certificate from the Let’s Encrypt authority using the Certbot software. You must type the following to get the TSL/SSL certificate.

sudo certbot certonly --webroot --webroot-path /your/project/root/public/directory/path  -d example.com

Let’s quickly explain what the Certbot options do:

certonly: This option tells Certbot only to obtain the certificate, and you will do the manual installation.
— webroot: The webroot plugin requires that you specify a directory on your server where Certbot can place a temporary file to prove that you have control over the domain you request a certificate for.
-— webroot-path: This specifies the directory where Certbot should place the temporary file.
-d: This option specifies the domain or subdomain you want to obtain a certificate.

If this is your first time running `certbot`, you will be prompted to enter your email address and agree to the service terms.

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
 (Enter 'c' to cancel): test@mail.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.3-September-21-2022.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: Y

If this command you just run is successful, certbot will ask how you would like to redirect traffic to HTTPS.

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel):

Hit the Enter Key when you are done making your choice. If successful, you should get a message that looks like this:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/example.com/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/example.com/privkey.pem
   Your cert will expire on 2023-07-18. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot again
   with the "certonly" option. To non-interactively renew *all* of
   your certificates, run "certbot renew"
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le

Step 3: Copy The TSL/SSL Certificates

Your certificates have been downloaded in this directory
/etc/letsencrypt/live/example.com/. You will need to copy out the certificates to a new directory /etc/letsencrypt with any symbolic links encountered in the source directory using the -L option so that the contents of the linked files are copied rather than just the link itself.

sudo mkdir -p /etc/letsencrypt/ssl #create an SSL directory to save the fullchain and privkey files 

sudo cp -r -L /etc/letsencrypt/live/example.com/fullchain.pem /etc/letsencrypt/ssl/
sudo cp -r -L /etc/letsencrypt/live/example.com/privkey.pem /etc/letsencrypt/ssl/

You might want to give the necessary permissions so that the certificates in the new directory are read only by a specific user and group as thus:

sudo chown <nginx_user>:<nginx_group> /etc/letsencrypt/ssl/fullchain.pem
sudo chown <nginx_user>:<nginx_group> /etc/letsencrypt/ssl/privkey.pem

Step 4: Update Docker-compose File

You should create another file and name it docker-compose-production.yml, assuming you already have a docker-compose.yml file you use locally. This is to differentiate the production docker-compose file, which would have the certificates referenced by paths.

So here is what your docker-compose-production.yml should look like after updating it.

nginx:
        container_name: example_nginx_prod
        image: nginx:latest
        ports:
            - "${SSL_PORT}:443"
            - "${HTTP_PORT}:80"
        volumes:
            - ./:/your/project/root/directory/path
            - /etc/letsencrypt/ssl/fullchain.pem:/etc/nginx/ssl/fullchain.pem
            - /etc/letsencrypt/ssl/privkey.pem:/etc/nginx/ssl/privkey.pem

Step 5: Update Your Nginx conf

The next step is to update your nginx conf file in your docker container to include the certificates like thus:

server {
    listen [::]:443 ssl;
    listen 443 ssl; 

    root /your/project/root/public/directory/path;
    index index.html index.php index.htm index.nginx-debian.html;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;

    server_name example.com;

    ssl_certificate /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    error_page 404 /index.php;

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

Step 6: Rebuild The Docker Container

At this point, you are done with the hard part. You need to rebuild the docker container for your changes to take effect. For example, using docker-compose, you could do it this way:

docker-compose -f docker-compose-production.yml build

Note: You can use the no-cache option if need be.

docker-compose -f docker-compose-production.yml build --no-cache

Now, bring your docker container back up using this command.

docker-compose -f docker-compose-production.yml up -d

Conclusion:

Following this tutorial, you have successfully secured your Nginx Docker container with Let’s Encrypt SSL certificates. Your web application now benefits from the highest level of encryption and trust, providing a secure environment for users to interact with your content.

Remember to renew your SSL certificates to maintain continuous security regularly.

Happy Learning :)!

How To Test Mail and Database Notifications in Laravel 8

MacDonald Chika — Wed, 11 May 2022 17:49:23 +0000

I was working on a project in Laravel and needed to test the mail content of a mail notification and also the database notification but I could not figure it out. After some research, I figured that you can actually unit test or assert mail notification content as well as database notification without sending an actual notification. I will show you how to do that in this article.

If you are reading this, I will assume that you already know how to write unit tests in Laravel using PHPUnit. If you don't , you can click here to get you started.

Firstly, we will create a notification using this Laravel command
php artisan make:notification TestNotification

Your file should look like this.


namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;

class TestNotification extends Notification
{
    use Queueable;

    private $user;

    public function __construct($user)
    {
        $this->$user = $user;
    }

    public function via($notifiable)
    {
        return ['mail','database'];
    }

    public function toMail($notifiable)
    {
        return (new MailMessage)
                    ->line('The introduction to the notification.')
                    ->action('Notification Action', url('/'))
                    ->line('Thank you for using our application!');
    }

    public function toArray($notifiable)
    {
        return [
            'some' => 'data'
        ];
    }
}

And then in your test, you should fake the notification by calling the notification facade and then a static function fake().

We are going to test the database notification. In your test file, create a function testDatabaseNotification(). Afterward, we will arrange our test case, act and assert.

public function testDatabaseNotification()
    {   
        // Arrange
        Notification::fake(); 
        $this->user = User::factory()->create();
        $email_subject = "Test Notification";

        // Act 
        $this->user->notify(new TestNotification($email_subject));

        // Assert
        Notification::assertSentTo($this->user, TestNotification::class, function ($notification, $channels) use($email_subject){
            $this->assertContains('database', $channels);

            $databaseNotification = (object)$notification->toArray($this->user);
            $this->assertEquals( $email_subject, $databaseNotification->title);

            return true;
        });
    }

Now we are going to test our mail notification

public function testMailNotification()
    {   
        // Arrange
        Notification::fake();
        $this->user = User::factory()->create();
        $email_subject = "Test notification";

        // Act
        $this->user->notify(new TestNotification($email_subject));

        // Assert
        Notification::assertSentTo($this->user, TestNotification::class, function ($notification, $channels) use($email_subject){
            $this->assertContains('mail', $channels);

            $mailNotification = (object)$notification->toMail($this->user);
            $this->assertEquals($email_subject, $mailNotification->subject,);

            $this->assertEquals('The introduction to the notification.', $mailNotification->introLines[0]);
            $this->assertEquals('Thank you for using our application!', $mailNotification->outroLines[0]);
            $this->assertEquals('Notification Action', $mailNotification->actionText);
            $this->assertEquals($mailNotification->actionUrl, url('/'));

            return true;
        });
}

You see here that we are retrieving the content of the mail notification.

Here is the full code

<?php

namespace Tests\Unit;

use App\Notifications\TestNotification;
use Illuminate\Support\Facades\Notification;
use App\Model\User;
use Tests\TestCase;

class MailNotificationTest extends TestCase
{
    /**
     * @var \Illuminate\Database\Eloquent\Collection|\Illuminate\Database\Eloquent\Model|mixed
     */
    private $user;

    /**
     * A basic test example.
     *
     * @return void
     */
    public function testDatabaseNotification()
    {
        Notification::fake();
        $this->user = User::factory()->create();
        $email_subject = "Test Notification";

        $this->user->notify(new TestNotification($email_subject));

        Notification::assertSentTo($this->user, TestNotification::class, function ($notification, $channels) use($email_subject){
            $this->assertContains('database', $channels);

            $databaseNotification = (object)$notification->toArray($this->user);
            $this->assertEquals( $email_subject, $databaseNotification->title);

            return true;
        });
    }

    public function testMailNotification()
    {
        Notification::fake();
        $this->user = User::factory()->create();
        $email_subject = "Test notification";

        $this->user->notify(new TestNotification($email_subject));

        Notification::assertSentTo($this->user, TestNotification::class, function ($notification, $channels) use($email_subject){
            $this->assertContains('mail', $channels);

            $mailNotification = (object)$notification->toMail($this->user);
            $this->assertEquals($email_subject, $mailNotification->subject,);

            $this->assertEquals('The introduction to the notification.', $mailNotification->introLines[0]);
            $this->assertEquals('Thank you for using our application!', $mailNotification->outroLines[0]);
            $this->assertEquals('Notification Action', $mailNotification->actionText);
            $this->assertEquals($mailNotification->actionUrl, url('/'));

            return true;
        });
    }
}

Now we have successfully asserted mail and database content in Laravel notification.
Please share in the comment below what you think about this.

Happy Coding :)

How To Make Laravel Pusher Work In Production

MacDonald Chika — Sat, 12 Feb 2022 12:28:12 +0000

If you have ever deployed your laravel code to production environment and then you realized that for some reasons Pusher does not work in your production environment , then you are not alone. I will show you how to make Pusher work in your production environment from the server side.

To make Pusher work in production, we need to ensure that Pusher has been set up correctly in our application. Let's set up Pusher on our existing Laravel application. If you have already installed Pusher, then skip to the next step.

If you don't know how to create a fresh Laravel application click here

Step 1: Install Pusher

composer require pusher/pusher-php-server

Once installation is complete, we'll make sure that Laravel broadcasting is registered in config/app.php. Go to config/app.php and uncomment the line below in the providers array.

// App\Providers\BroadcastServiceProvider

If you need to know more about creating and defining events then take a look at this

Step 2: Configure Pusher

We will configure our pusher app credentials in config/broadcasting.php. We will create and get our Pusher credentials from here. And now. we'll supply our credentials in the .env file as thus:

PUSHER_APP_ID=xxxxxx
PUSHER_APP_KEY=xxxxxxxxxxxxxxxxxxxx
PUSHER_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
PUSHER_APP_CLUSTER=xx

Replace the xs with the actual pusher credentials

Now, we need to modify the pusher array in config/broadcasting.php so that it looks like this:

'pusher' => [
    'driver' => 'pusher',
    'key' => env('PUSHER_APP_KEY'),
    'secret' => env('PUSHER_APP_SECRET'),
    'app_id' => env('PUSHER_APP_ID'),
    'options' => [
        'cluster' => env('PUSHER_APP_CLUSTER'),
        'useTLS' => true,
        'encrypted' => true,
    ],
],

Step 3: Update .env and Run Artisan Command

We will now change the value of our broadcast driver in the .env from log to pusher. This tells Laravel what broadcast driver to use when implementing ShouldBroadcast interface in our event class.

BROADCAST_DRIVER=pusher

And finally, run this command in your production environment

php artisan config:clear

You might want to run the following command;

php artisan tinker

and then check that your broadcasting configuration is correct - particularly the default connection which should be pusher - with the following line of code.

config('broadcasting');

If you have followed the steps above, then your events should work fine now.

Conclusion
You have learned how to make Pusher work in a production environment.

Please note: there could be a number of reasons why your Pusher events do not work in your production environment. This is just one of them.

Test-Driven Development (TDD) in Laravel 8

MacDonald Chika — Tue, 25 Jan 2022 18:17:50 +0000

Before we delve into Test-Driven Development, let's first define the term TDD.

What is Test-Driven Development(TDD)?

**
According to Wikipedia, "Test-Driven Development is a software development process relying on software requirements being converted to test cases before the software is fully developed, and tracking all software development by repeatedly testing the software against all test cases".

It is a software development approach that emphasizes writing bug-free codes by developing test cases to specify and validate what the code will do.

Here is what Test-Driven Development (TDD) cycle looks like;

Write a test
Run the test -- which will fail
Write some code
Run the test again
Make changes to code to make the test pass(refactor)
Repeat

How To Write Tests in Laravel

For the purpose of this article, we will create a simple CRUD API to create, read , update and delete blog posts. Let's begin by creating a fresh Laravel project by using Composer.

Step 1: Create and initialize the project
composer create-project laravel/laravel blog

cd blog

You can run the command below to be sure that everything works fine
php artisan serve

Step 2: Set up your test suite
Update your phpunit.xml file in your root directory. Uncomment these lines of codes.

<server name="DB_CONNECTION" value="sqlite"/>
<server name="DB_DATABASE" value=":memory:"/>

The updated file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true">
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">./tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory suffix="Test.php">./tests/Feature</directory>
        </testsuite>
    </testsuites>
    <coverage processUncoveredFiles="true">
        <include>
            <directory suffix=".php">./app</directory>
        </include>
    </coverage>
    <php>
        <server name="APP_ENV" value="testing"/>
        <server name="BCRYPT_ROUNDS" value="4"/>
        <server name="CACHE_DRIVER" value="array"/>
        <server name="DB_CONNECTION" value="sqlite"/>
        <server name="DB_DATABASE" value=":memory:"/>
        <server name="MAIL_MAILER" value="array"/>
        <server name="QUEUE_CONNECTION" value="sync"/>
        <server name="SESSION_DRIVER" value="array"/>
        <server name="TELESCOPE_ENABLED" value="false"/>
    </php>
</phpunit>

We uncommented or added those lines of code to ensure that PHPUnit uses :memory: database so that tests run faster. Now that our test suite is set up, let’s set up our base test file TestCase.php

<?php

namespace Tests;

use Faker\Factory as Faker;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Illuminate\Support\Facades\Artisan;

abstract class TestCase extends BaseTestCase
{
    use CreatesApplication, RefreshDatabase;

    protected $faker;

    /**
     * Sets up the tests
     */
    public function setUp(): void
    {
        parent::setUp();

        $this->faker = Faker::create();

        Artisan::call('migrate'); // runs the migration
    }


    /**
     * Rolls back migrations
     */
    public function tearDown(): void
    {
        Artisan::call('migrate:rollback');

        parent::tearDown();
    }
}

You would notice that we use the RefreshDatabase trait because it is often useful to reset our database after each test so that data from a previous test does not interfere with subsequent tests. You may also notice that we added two methods setUp() and tearDown(). The former is run by the test runner prior to each test and the latter after each test. They help keep your test code clean and flexible.

Step 3: Create and write your test
To create a test file in laravel 8, simple run this artisan command

php artisan make:test PostTest

The command above creates a PostTest.php file in tests/Feature directory.

The next thing we need to do is write our actual test.

Note: You will need to either prefix your methods name with test i.e testCanCreateAPost or use the /** @test / annotation. That way **PhpUnit* knows that it needs to run your test.

<?php

namespace Tests\Feature;

use Tests\TestCase;

class PostTest extends TestCase
{
    /** @test*/
    public function canCreateAPost()
    {
        $data = [
            'title' => $this->faker->sentence,
            'description' => $this->faker->paragraph
        ];

        $response = $this->json('POST', '/api/v1/posts', $data);

        $response->assertStatus(201)
             ->assertJson(compact('data'));

        $this->assertDatabaseHas('posts', [
          'title' => $data['title'],
          'description' => $data['description']
        ]);
    }
}

Step 4: Run your test
Now we need to run our test with phpunit as thus:

./vendor/bin/phpunit

or laravel artisan command which is pretty cool as it provides verbose test reports in order to ease development and debugging:

php artisan test

Oops! Our test FAILED! is this good? Yes, it is in fact fine for our test to fail as it follows the second rule of TDD that it should Fail after creating the test.

So why did our test fail?

The error says the expected response code is 201 — as we have asserted in our test — but received** 404 (Not found). This means that the endpoint [POST]‘/api/v1/posts**’ does not exist and we need to create one. This brings us to the next step.

Step 5: Make Test Pass
What we will be doing in this step is to make our test pass. First to get rid of the 404 error, let create an endpoint.

CREATE THE ENDPOINT IN YOUR ROUTE FILE
let’s go to our route file located at ‘routes/api.php’ and create that endpoint. All routes created in this file are automatically prefixed with ‘/api’.

php artisan make:controller --resource

You can either run this command to create a RESTful controller in the /app/Http/Controllers/Api directory or you can create it manually.

Now let’s debug our controller and validate our request

In the store method, where the POST request goes, return a response as thus:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class PostController extends Controller
{

    public function index()
    {
        //
    }

    public function create()
    {
        //
    }

    public function store(Request $request)
    {
        return response()
            ->json([
                'message' => 'Post created'
            ]);
    }


    public function show($id)
    {
        //
    }


    public function edit($id)
    {
        //
    }


    public function update(Request $request, $id)
    {
       //
    }

    public function destroy($id)
    {
        //
    }
}

We will create a request file containing some validation rules to validate the data going into our database.

php artisan make:request CreatePostRequest

Remember to change false to true in the authorize() method

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class CreatePostRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            'title' => ['required'],
            'description' => ['required']
        ];
    }
}

We are going to import and pass our CreatePostRequest to the store method of our controller. The store() method in our controller should now look like this:

public function store(CreatePostRequest $request)
{
    return response()
        ->json([
            'message' => 'Post created'
        ]);
}

Note: Remember to import the CreatePostRequest class.

CREATE YOUR MODEL AND MIGRATIONphp artisan make:model Post -m

php artisan make:model Post -m

This artisan command creates our model and migration. The -m flag creates a migration file under database/migrations directory. We will add title and description columns in our migration as thus:

<?php

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

class CreatePostsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->string('description');
            $table->timestamps();
        });
    }

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

And in our Model, we have to define the hidden and fillable fields.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;


class Post extends Model
{
    use HasFactory;

    protected $fillable = [
        'title',
        'description'
    ];
}

Once that is done, we will edit our store method as thus:

public function store(CreatePostRequest $request)
{
    $data = $request->validated();  // only validated request

    $post = Post::create($data);   // creates and return post

    return response()
      ->json([ 
        'message' => 'Post created'
      ]);
}

Note: remember to import the Post class in your controller

RE-RUN TESTS

php artisan test

Our test Failed again but this time it says that it can’t assert that 201 is identical to 200. This means that our endpoint returns a 200 response code instead of a 201. So let’s add a 201 response code — which means that the resource was successfully created.

public function store(CreatePostRequest $request)
{
    $data = $request->validated();  // only validated request

    $post = Post::create($data);   // creates and return post

    return response()
        ->json([ 
            'message' => 'Post created'
        ], 201);
}

let's re-run our test again.

Note: if you get a 500 response code, you can take a look at the log file at /storage/logs/laravel.log.

Now we get another error. It can’t assert that a certain JSON exists, which was defined in our test here

$data = [
    'title' => $this->faker->sentence,
    'description' => $this->faker->paragraph
];
$response = $this->json('POST', '/api/v1/posts', $data);
$response->assertStatus(201)
      ->dump() // use this to know what data is being returned 
     ->assertJson(compact('data')); // this line here

To solve this, we need to return the created resource to assert that it matches the data that is being sent to the endpoint. So, within our store() method will add a ‘data’ object that returns the newly created resource to our payload.

public function store(CreatePostRequest $request)
{
    $data = $request->validated();  // only validated request

    $post = Post::create($data);   // creates and return post

    return response()
        ->json([
            'data' =>  $post,
            'message' => 'Post created'
        ], 201);
}

Once that is done, we will re-run our test.

WELL DONE! You have made the test pass.