Posted on

Full-featured multi-tenant Laravel app from scratch

Ashok Gelal

More than enough words have been written about the simplicity and the greatness of Laravel framework. Unlike the rumors, you can actually create solid web apps of varying complexity with it and some absolutely amazing optional official packages, which there are plenty.

It’s not just about the framework itself, the whole ecosystem is great. There are so many community libraries — everything from managing permissions, to supporting JWT authentication for your APIs, to managing teams. And you’ll have no problems finding good documentation and great tutorials.

But sadly one thing Laravel ecosystem seriously lacks is complete tutorials on writing a complex app. The only one I’ve seen that is somehow complex is “Let’s Build A Forum with Laravel and TDD” by Jeffrey Way. Most other so-called “how to do complex things in Laravel” tutorials/ articles mostly give you a rundown of libraries to use.

This could mean two things — either people are not writing a complex app with Laravel (and this is one thing that gets a lot of crap for with his framework) or people are too busy writing complex Laravel apps that they don’t have time to write about it. Having written at least a 2–3 complex apps at work myself, I truly believe it’s the latter. You don’t blame us for doing our job well and not having enough time to share our knowledge. Do you? 😉

Recently at work, I was assigned on writing a multi-tenant app for an upcoming real project that, once it is released, should be used by hundreds of tenants (companies), where each company will have anywhere from 25–10,000 users. So you can call it a fairly complex project. At least in my 8 years of professional software developer career, this is certainly the most complex project I’ve worked on (my most complex non-professional project would probably be the Dash project I did as a Computer Science undergrad student at Boise State).

Anyway, I didn’t find any good documentation or even a sample app on Laravel and multi-tenancy. There were few articles on it but no code to look at or nowhere to ask questions if you are stuck. I was embracing myself for having to write everything from scratch and learning by making mistakes.

While the latter part, learning by mistakes, had to be done, thankfully I didn’t have to write everything from scratch and start with a blank canvas as I stumbled upon a great library for multi-tenancy, aptly named Multi-Tenant. It gave me a great start but it still lacked good examples.

Seriously, you install the package and then you have no idea where to go next. And there are a number of things I ran across where there was no documentation, or lacked a feature and I’ve to go through the source code to understand how to get certain things done or even monkey-patch it in some places. The package has got better in the last couple of iterations but the lack of good documentation still holds true, I think.

I also found out there are few quirks in Laravel framework itself that doesn’t work for a multi-tenant app without a workaround. For an example, sending a Reset Password email to a tenant user. The URL generated in ResetPassword.php doesn’t point to a tenant’s domain causing an error when setting up a new password after clicking the link.

So, after falling, failing, getting up and then repeating the cycle a lot during the course of writing a real and complex multi-tenant app, I want to share my knowledge and show you how to setup, write, and deploy a multi-tenant app using Laravel and Multi-Tenant library. We will create a full-featured app with support for roles and permissions, APIs, admin panel and few more. The app will allow users for listing rentals and we’ll call this app Townhouse. Punny isn’t it?

Think of Townhouse as a clone of Craigslist but only focused on property rentals. A super admin (that is you) will be able to create a city (which will be our tenant) and assign an admin to manage the city’s rentals. Rental owners tenant’s users) will be able to signup and list their property.

I’ll do my best to write as many posts as possible to guide you through every major step of the app. Or you’ll be able to clone the project and play with it from GitHub as new features get implemented.

In the next post, we’ll setup a new Laravel project, install dependencies, setup the database, create few console commands to bootstrap a tenant and start playing with the tenant admin UI.

Looking for an easy way to provision a server and deploy your Laravel apps? Try Cleaver 👇

Need Help?

If you have any questions, comments, or need help with a multi-tenancy app, come join us in our Slack channel.

Read Part 1 — Setup >