Exploring Subdomain Management with Laravel and Local Docker

Introduction

Subdomain management is a powerful feature that allows developers to create separate sections or functionality within a single domain. Using subdomains can help organize and streamline different components of a web application. In this article, we will look at managing subdomains in a Laravel application and creating a local development environment using Docker.

Setting Up Laravel with Docker

Before we dive into subdomain management, let’s set up a Laravel application using Docker. Docker simplifies managing development environments by encapsulating all dependencies into containers. Laravel Sail is a great tool to get started with Docker in Laravel.

Step 1: Installing Laravel Sail

To install Sail, run the following command:

composer require laravel/sail --dev

Use https://laravel.com/docs/11.x/sail to learn more about Sail.

Step 2: Configuring Docker for Subdomain Support

To create custom domains and proxy them, we will use Traefik. The main advantage of Traefik is that it saves you from having to modify the host file in your operating system to access a custom domain, and it also supports subdomains.

Create a docker network

Let’s create a new global network to connect the two containers.

docker network create web

Create Traefik container

Use this repository to learn more:
https://github.com/dipaksarkar/laravel-sail-with-traefik

You can create Traefic in your docker file where Laravel, Database, etc. You can install Traefik in a Docker configuration along with Laravel, database, and other services.

# Go to traefik directory
cd traefik

# If it's the firt install of mkcert, run
mkcert -install

# Generate certificate for domain "docker.localhost", "domain.local" and their sub-domains
mkcert -cert-file certs/local-cert.pem -key-file certs/local-key.pem "your-domain.localhost" "*.your-domain.localhost"

# Start traefik container
docker-compose up -d

After the container starts successfully we can access the Traefik dashboard via http://traefik.docker.localhost.

Start the Traefic

docker-compose up -d

Step 3: Setting up a Docker file for Laravel

Add labels to your configuration file. Remember to change the name of the service to your service (traefik.http.routers.{your-container-name}.rule.

labels:
    - "traefik.enable=true"
    # Here we have to define the URL
    # More details https://doc.traefik.io/traefik/v2.0/routing/routers/#rule
    - "traefik.http.routers.{your-container-name}.rule=HostRegexp(`your-domain.localhost`, `{subdomain:[a-z]+}.your-domain.localhost`)"
    - "traefik.docker.network=web"
    - "traefik.http.services.{your-container-name}.loadbalancer.server.port=80"
    # Activation of TLS
    - "traefik.http.routers.{your-container-name}.tls=true"

Add a new network:

app:
  ...
  networks:
    - sail
    - web #(new network)
networks:
    sail:
        driver: bridge
    web:
        external: true

Step 4: Configure the Laravel application

Laravel also supports wildcard subdomain routing for dynamic subdomains. Add this code for those routes you want to use with subdomains.

$domain = env('APP_DOMAIN');
Route::domain('{organisation}.' . $domain)->group(static function () {})

If you want to get an entity (in my case Organisation) from your Request, then let’s write such Middleware:

class HandleOrganisationDomain extends Middleware
{
    public function handle(Request $request, Closure $next): Response
    {
        if ($slug = $request->route('organisation')) {
            // Store the organisation in the request context
            $request->attributes->set('organisation', Organisation::where('slug', $slug)->firstOrFail());
        }

        return $next($request);
    }
}

If you don’t like this solution, you can always use laravel bindings and just get the model in any controller method.

Conclusion

If you have done everything correctly, your local environment now supports custom domains with automatic resolving of DNS, subdomains, and SSL certificates. Using Laravel Sail and Docker, you can quickly create a local environment and efficiently manage subdomain routing. This approach not only simplifies the development process but also ensures a clean and maintainable codebase.