Designing an Installation Script

A whole article for an installation script. Really? Yup. I believe this is probably one of the most important pieces of your application design. The goal is to make your app self-hostable and make it easy. An installation script makes it super easy for a user to get off the ground. Everything is set up and ready to go in the most minimal amount of steps.

What to Include

Basically, anything to get the application configured and off the ground as quickly and bulletproof as possible. This could super admin credentials, database seeding and migrations, essential settings, etc. Anything the user needs to see the GUI of your app, assuming it's GUI based.

What NOT to Include

Onboarding. The goal is to get TO the onboarding. What's the difference? The installation script should simply get the app running so when the user visits the URL of the application, they see something that's not an error screen. Onboarding is the UI the user will see to guide them through the rest of the set up.

Think of the installation script as whatever it takes to power on your app. Once it's powered on, then you can design an onboarding wizard.

Prompting for Information

If there is essential information and settings, it may be helpful to prompt for this within your installation script. Don't prompt for too much, that will be in the onboarding. Think within the context of "super admin" permissions. Whatever can set up the super admin logged in is what we need to prompt for.

Example with Bugflow

We just went through this process with Bugflow. Once the user pulls down the docker image, they need to run php artisan bugflow:init. We use Laravel, so it's an artisan command.

With this command, we:

1. Configure the app key. This is essential for Laravel and encryption.
2. Set up the database and migrate all the necessary tables.
3. Initialize a super admin registration token.
4. Display a secure register link with this token to create a super admin user.

It's a simple script that's absolutely essential. It's also scalable. Instead of giving individual commands to initialize, we give one command that sets up everything. If we add more features and need more configuration, we can easily extend this command. Finally, once everything is set up, we create a unique token and print out a signed authentication URL in the terminal. The user can go to that URL and enter their super admin credentials in the UI. We hand off the rest of the onboarding from there.

Update Script

Another pain point of managing a self-hosted application is running updates. We always provide an update script that the user can run that will take care of any of the data migrations or setting re-configuration automatically.

With this script, we also prompt for questions to help guide the update. Maybe the user wants to format a migration a certain way, or move data in to this place instead of that. If there are options available like that, we prompt the user. Anything to take the pain out of running a series of commands.

Wrapping Up

Self-hosting can be intimidating so making installation and maintenance seamless as possible will help you retain satisfied users. You don't want your users starting off on the wrong foot with an error screen and a bunch of rage. It's exciting to own your data and keeping people excited is part of the process. A simple installation script and organized update script make your app feel so much more polished and put together.