search

nikspyratos / toybox

Opinionated TALL stack starter kit for Laravel solopreneurs
MIT License
117 stars 6 forks source link
alpinejs caddy filament frankenphp laravel livewire php sqlite

readme

Toybox - A TALL SaaS starter kit

Toybox cover image

Toybox is an enhanced TALL stack installer for Laravel, aimed for experienced developers and solopreneurs.

Even if you don't need another boilerplate, perhaps the list of recommended services will still give you a path forward, or the scripts will give you something to work with.

Alternatively if you're looking for more functionality out of your boilerplate, take a look at Sergey Karakhanyan's Larafast.

This project is intended mostly for use as a solo Laravel developer who wants to rapidly develop and deploy indie SaaS projects. This is not intended for junior developers - having worked with the modern Laravel ecosystem is ideal to use this project. This is also not intended for "professional" commercial use, i.e. for freelance clients - it's intended for use by indie developer-entrepreneurs.

Principles

Support this project

Project Status

It is currently in a beta state.

Toybox has been completely transformed from a template into a Bash-based install script. It needs a bit more testing to get it over the line.

This was done to reduce the maintenance requirements of including ever-changing framework files, while still keeping what makes the project useful.

For some core files it's more prudent to replace them outright, but this is kept to a minimum (namely the User model and Filament AdminPanelProvider).

Features

All of this is done while keeping package dependencies minimal outside of trusted third parties like Filament or Spatie.

Components

Installation/Usage

Requirements

You will need PHP 8.3 alongside some extensions (at least the Laravel defaults and intl)

A good starting point of extensions that should cover most apps is:

bcmath
ctype
curl
dba
dom
fileinfo
filter
gd
gettext
gmp
iconv
intl
libxml
mbstring
mysqli
openssl
pcntl
PDO
Phar
posix
session
soap
sockets
tokenizer
zlib

Local Development

Environment Setup

Cross-platform
macOS

Note: Favicons with Valet-hosted sites are a bit broken. To fix it, edit your /opt/homebrew/etc/nginx/valet/valet.conf using one of simensen's workarounds, or just remove the favicon & robot.text handlers entirely.

Linux
Windows

Note: If using Herd, you won't be able to use Horizon and Pail, as they require the pcntl extension which does not work on Windows. If you really need these tools, you'll need a WSL2/Docker/VM based development environment. Third party packages using Prompts may also fail, as while Prompts has a fallback for Windows, this has to be implemented manually for other OSes.

Installing Toybox

  1. Clone/fork this repository into a new repository.
  2. Make sure you have the necessary dependencies installed
    1. composer needs to be configured in your PATH so global composer scripts can run.
  3. Run ./init.sh (remember to do so from WSL2 on Windows). It will:
    • Ask you for some basic environment variables (repo name, app name, domain).
    • Run the Laravel installer with pre-defined settings
    • Install additional packages, modify environment files and settings, and configure the app to run as intended.

Note: By default init.sh assumes your production server username is ubuntu. If it is not, you need to replace ubuntu in your Caddyfile.prod, templates/octane.conf and templates/reverb.conf with the correct username, once init.sh is finished.

Once the script completes, you can commit the changes to the edited files.

For details, look in init.sh.

The sections below outline the recommended way to work with Toybox on your local system. Please note the included Caddyfile.prod is intended for production use and Caddyfile.dev for local testing..

Laravel Octane

The default Octane config will start with one worker per core, and restart workers every 500 requests. To account for this project's dependencies and any potential leaks, Toybox's config is a bit more conservative and will restart workers every 250 requests. You can change this in templates/octane.conf.

To use Octane with Valet/Herd, you'll need to proxy your site to your octane port.

Code Quality & Analysis

Five tools have been included for this:

There are also some default Pest tests for architecture rules as well. You may see some overlap or conflicts in recommendations by these tools - if so, please make an issue so I can adjust the config to avoid the conflict.

By default, you will already have Duster & Rustywind running as a pre-commit hook. Larastan and PHP Insights can be run individually, or as a group with the command composer run analysis. Security Advisories runs on composer operations, to prevent installation of insecure packages. Note that PHP Insights is configured to automatically fix issues it is able to fix. You may also want to look inside config/insights.php and add/change any sniffs per your preference - there are some rules that may be too strict for some users.

The commands for all the tools are:

./vendor/bin/duster fix
./vendor/bin/duster lint #Linting may catch issues that fix can't resolve
./vendor/bin/phpstan analyse
php artisan insights

For Duster, if there are any unfixable issues raised in duster fix, you can get more info on them by running duster lint. Also note that you can add the --dirty flag to only run it for files that have changed.

Some analysis steps in these tools may fail on a default Toybox installation. Where reasonable I've tried to mitigate this, but some will be left up to you as the developer. Some fixes require opinionated configurations that I don't feel Toybox should have a default on.

Next Steps - DIY

These are the next steps you will have to implement yourself for your project as your needs change & scale.

Post-Setup

Ongoing Development

Production

Provisioning

This assumes you're starting from scratch on an unmanaged Ubuntu server with an ubuntu user that has sudo access.

Note: The provision_prod.sh and deploy.sh scripts are intended for early use in your SaaS. Once you need to go beyond vertical scaling, I'd highly recommend getting started with the recommended infrastructure and deployment tools.

Your first step is to download your project repository from your VCS. Then, run ./bin/provision_prod.sh from the project directory. It will:

Once this is done, update your local .env's DEPLOYMENT_PATH and Caddyfile's APP_PATH as prompted by the output. This is to enable the deploy.sh script to work and to keep your Caddyfile in line with the production version.

If you're using websockets, you will also want to manually copy the templates/reverb.conf config over for Supervisor to run reverb for you.

For more details, look in templates/bin/provision_prod.sh.

Manual steps

Naturally, you'll also need to configure your own DNS records to point your domain to your webserver.

When your application goes live, make sure to update the last updated dates of the terms & privacy policy pages to your launch date.

Deployment

In your local project, edit the following variables to your local .env, using the appropriate values:

DEPLOYMENT_IP=
DEPLOYMENT_USER=
DEPLOYMENT_SSH_KEY=

DEPLOYMENT_PATH should already be set up from when you ran init.sh. If not, please edit it to the appropriate value.

To deploy the latest application changes, run ./bin/deploy.sh. It will:

Troubleshooting

This is where your skills come in.

Caddy having issues obtaining SSL

Make sure your firewall rules allow incoming traffic on port 443. This includes checking security settings with your hosting provider, e.g. AWS security groups.

3rd-party Services/Tools

This is a list of options, not requirements. You can likely run your SaaS perfectly fine without many of these.

This list includes both commercial options and open-source, including packages.

For more, search for awesome-laravel repos on Github, like this one.

AI (LLMs)

The community-built OpenAPI PHP SDK is robust for building AI into your applications. Sparkle is another great tool (coming soon).

Analytics

Fathom and Plausible are great options. If I had to choose: Fathom has more accessible pricing, and is made with Laravel!

For tracking user actions in your app, Spatie Activity Log is great.

API Tools

Treblle provides a great suite of tools for API observability, security, analytics and more. The Laravel SDK is here.

Backups

Cache

Laravel Response Cache is a good starting point for caching frequently accessed & frequently unchanged pages. Beyond that, Varnish is excellent and as usual there's a Spatie package for it.

CMS

Statamic has excellent integration directly into Laravel apps. The core CMS functionality (without any frontend or control panel features) is FOSS, otherwise it's free for solo usage. For advanced features in a business use case with e.g. a marketing/writing team, it's recommended to pay for Pro.

Alternatively, there are plenty of other blog/content site providers out there, e.g. Wordpress. The CMS space is too huge to make any more specific recommendations.

If you want something free & simple for creating content for your app, consider using Jigsaw - a static site generator that uses Markdown & Blade. It's free and easy to use. If hosting it with Github Pages, have a look here on how to remove build artifacts from your main branch.

Code Generation

Blueprint by the Laravel Shift team is a great addition.

Containerisation

Beyond Docker, check out Colima (macOS + Linux) and Orbstack (macOS) as alternative runtimes that will save your system resources.

Data Analysis

I highly recommend checking out Metabase for this. While it's fairly simple to make graphs/dashboards and track database metrics with Laravel/Filament, Metabase is more specialised for the task and separates concerns nicely. It can also be self-hosted!.

Debugging

If you're a dd fan, Ray is a great addition.

Deployment - CI/CD

Forge & Ploi offer deployment, but Envoyer is a great addition.

As a deployment management layer over Docker, see Kamal

Desktop

While still in alpha, NativePHP will hopefully be a very promising option if you'd like to add desktop apps to your toolkit.

For a ready-to-go desktop-based database management/admin panel for your application, Invoker is worth a look.

Documentation

For documentation within your app, see LaRecipe.

Event tracking/system notifications

I recommend LogSnag.

File Storage

Consider using any S3-compatible storage service. The ordinary local disk may be enough for your use case, but it may be prudent to separate this from your app. That way if you don't need a big server but need lots of storage, you don't have to scale your server costs unnecessarily (storage is much cheaper!).

Infrastructure

Laravel Forge and Ploi are good options (I prefer Ploi) and support many cloud providers. I lean towards AWS, but only because they have a Cape Town region.

Open source alternatives include Deployer, Eddy, and VitoDeploy

Otherwise, generalised provisioning tools like Ansible, Chef or Puppet should work.

Logging

Laravel Pail gives tail-like log tracking in your terminal, for any log driver. For application monitoring, see Uptime & Monitoring

Mail Provider

Laravel recommends Mailgun, Postmark and SES. Another option that integrates well, and works for newsletters/marketing campaigns too, is Mailcoach.

Media Library

Spatie's Media Library Pro is excellent. See below for free version details.

Mobile

Yeah, nah. Maybe some mad scientist has gotten this one right, but I'd recommend sticking to "normal" mobile tech.

Payment Provider

There are a few options here, depending on your region. For many countries, Stripe with Laravel Cashier will be fine. Otherwise, have a look at Paddle (also has a Cashier plugin) or Lemon Squeezy (Laravel package here) for a Merchant of Record.

If you're in Africa, Paystack is a solid option (affiliate signup: here).

For more options, and whether or not you need an MoR, and taxation info see here.

Security

Have a look at Securing Laravel, and packages like Treblle security headers for reference.

Search

Algolia and Meilisearch are the ones supported by Laravel Scout. Meilisearch can be self-hosted, but can be a handful to manage and would still cost a fair bit in storage/RAM requirements, so you might not save much in time & headaches over using cloud.

Serverless

Either Laravel Vapor or roll-your-own setup for free with Bref. Note: this project is untested with serverless. If you get it working with any modifications, make a PR for adding your setup or instructions!

Uptime & Monitoring

I recommend OhDear. For error monitoring, Flare is also good.

Laravel Pulse is the latest offering in the OSS Laravel suite. Note however it won't work with SQLite databases.

Upgrading Laravel & PHP

For upgrading PHP, see Rector.

For upgrading Laravel, see Laravel Shift.

User Interface

For more recommendations, see here.

Websockets

Laravel Reverb is one of the newest ecosystem additions for this exact purpose.

Soketi and Laravel Websockets are a good alternatives.

Pusher and Ably are great paid options.

All options are to be used alongside Laravel Echo. If you want to DIY, see below.

Other Tools not included

For more niche suggestions and general Laravel resources, check out my Laravel links page.

For more tutorials, packages and more, make sure to look at Laravel News.

Filament Plugins & Tricks

This boilerplate relies heavily on FilamentPHP for the admin panel building. This also means there are plenty of extra resources to augment either your UI or admin panel:

Design

How to scale

This project is a starting point, but as your app scales, you may need to add some more pieces to keep it stable & safe.

You can do most of what is described below with the infrastructure tools recommended.

If you need even more than that:

Other recommendations for business operations, launching, etc.

While this isn't really within the scope of this project, I think it's still valuable to provide some starting recommendations for other entrepreneurs.

The following is a non-exhaustive, and potentially outdated list of recommendations.

For more resources, such as for launching, advertising, sales, marketing, communities, and incorporating a business, see here.

Helpdesk/Support

Honestly, using a support@example.com email address will be most of what you need.

Helpdesk systems are only really needed as you need to start building support teams and processes.

Nevertheless, some options are: Crisp.chat, GrooveHQ, HelpScout, and HelpSpace.

Live Chat

Many of the Support recommendations will already have a live chat feature. Otherwise, have a look at Tawk.to and Intercom.

Knowledgebase

While you're solo, I'd recommend one of the following:

Once you need to start having the knowledgebase available to others, Notion is my go-to. Notion also supports making public pages, so you can also have your customer knowledgebase there.

Roadmap Management

Suggest.gg

Accounting

I don't know too much in this space other than Xero.

Terms & Conditions

Contributing

These are some features that would be nice to have, but I don't intend on building yet for one reason or another:

Back to top