bjorndcode/serve

Quickly spin up local environments

Serve

Serve helps you quickly spin up local environments and run your projects isolated from the rest of your system.

Website

Note: Currently Serve works with Laravel projects.

Why Serve?

Serve's goal is to allow developers to quickly set up a local environment and create/run projects without any hassle—no need to install anything locally on your computer.

Too often, I've updated PHP only to find out that none of my projects worked anymore, that MySQL wasn't appropriately updated, and realised I have to spend several days running through Stack Overflow threads to find a solution.

Docker solves all the problems above. But it introduces a new problem. You now have to learn Docker. Serve abstracts all that away and allows you to never think about it again.

Serve does the following:

• Creates a docker environment for your project
• Installs services for PHP, NGINX, MySQL, Redis, etc. in the Docker environment.
• Starts / Stops the Docker container
• Provide other convenient features for managing your local environment

For more information, please read the VISION document.

Installation

1. Install and run Docker
2. Download Serve (Download the .dmg file)
3. Launch Serve

Usage

With Serve, you can import existing projects or create new ones.

For each project, you can specify versions for PHP and Node and choose database type and version.

A Serve project comes with a web server, so all you have to do is start the project and then access it.

All configuration files live in your repository. That makes it easy to share the configuration with teammates. If you ever want to stop using Serve, a fully-functioning docker-compose file can be run independently from Serve.

CLI

Serve has a CLI tool to run terminal commands. This means you don't need to have NPM installed locally to run NPM commands or Composer installed to run Composer commands. The CLI tool is automatically installed when openening Serve for the first time.

serve node
serve npm
serve yarn
serve mysql
serve mysqldump
serve psql
serve php
serve composer
serve phpunit
serve redis
serve redis-cli

Advanced

Customising Docker images

If you need to customise the Docker images for custom behavior you can do so with the following steps:

1. Create a docker folder
2. Create a Dockerfile inside the docker folder
3. Add changes to the Dockerfile

FROM bjornlindholm/laravel:7.4

// Add changes here

CMD ["supervisord"]

4. Update docker-compose.yml

Replace the following snippet

image: bjornlindholm/laravel:7.4

To build your own docker image

build:
  context: ./docker

Installing PHP extensions

If you need to install PHP extensions that aren't included in the base docker image you can do that by creating your own docker image. (See steps above)

FROM bjornlindholm/laravel:7.4

RUN apt-get update
RUN apt-get install -y php7.4-gmp

CMD ["supervisord"]

Roadmap

Please see ROADMAP for more planned features.

Contribution

Please see CONTRIBUTING for details.

Changelog

Please see CHANGELOG for details.

Credits

• Chris Fidao - For making https://serversforhackers.com/. His Docker series inspire much of the Laravel image.
• Local by Flywheel - For inspiration

Disclaimer

Serve isn't stable yet. Things might change, break, require reinstallation, etc.

Serve has only been tested on macOS. The goal is to support Windows and Linux soon, but it's not quite there yet. If you are using Windows or Linux, any testing, feedback, and fixes for those platforms are welcome.

serve's Issues

Fuzzy search in command palette

Currently the command palette uses a simple string comparison to search for commands. An added benefit to fuzzy search is that results will also be sorted by relevance instead of the order they are defined in.

Update db environment variables in docker-compose.yml

Example: If I change from mysql to postgress in the project settings it doesn't update docker-compose.yml with the changes after saving the settings.

Cannot open on MacOS BigSur "Launchd job spawn failed with error: 111"

When opening the application on macOS Big Sur, a system popup appears "You don't have permission to open the app Serve".

When trying to open using terminal: (with or without sudo)

The application cannot be opened for an unexpected reason, error=Error Domain=NSOSStatusErrorDomain Code=-10826 "kLSNoLaunchPermissionErr: User doesn't have permission to launch the app (managed networks)" UserInfo={_LSFunction=_LSLaunchWithRunningboard, _LSLine=2508, NSUnderlyingError=0x7fbf704086e0 {Error Domain=RBSRequestErrorDomain Code=5 "Launch failed." UserInfo={NSLocalizedFailureReason=Launch failed., NSUnderlyingError=0x7fbf70409e10 {Error Domain=NSPOSIXErrorDomain Code=111 "Unknown error: 111" UserInfo={NSLocalizedDescription=Launchd job spawn failed with error: 111}}}}}

Installing custom PHP extensions

Currently it's possible to install PHP extensions yourself but it's too complicated to do manually.

The current steps require you to do the following:

1. Create a docker folder in the project root
2. Create a Dockerfile inside the docker folder with the following contents:

FROM bjornlindholm/laravel:7.4

RUN apt-get update
RUN apt-get install -y php7.4-gmp

CMD ["supervisord"]

Where php7.4-gmp is the name of the extensions to install.
3. Update docker-compose.yml
Replace

services:
  app:
      image: bjornlindholm/laravel:7.4

With:

services:
  app:
    build:
      context: ./docker

Instead I would like to specify extensions in the serve.toml file and create a UI for it as well

Menu items for import and create

There should be menu item options for creating and importing projects.

Better quick actions

There are a few things that can be improved under the Quick Actions section:

• Change the editor button so that it remembers your choice
• Add an Open in database explorer button (Research if it can default to SequelPro or Tableplus)
• Consider adding Open in browser and Open in finder buttons. (These can already be opened from the table)
• Consider adding Open in terminal button

More smooth process for creating new Laravel projects

There are currently a few issues when creating a project.

• Automatically install predis/presis with composer
• Update .env file

---

These are the following keys that needs updating in .env:

DB_HOST=db
DB_PASSWORD=root
CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_CLIENT=predis
REDIS_HOST=cache

If you are using postgres instead of MySQL the following keys need to be updated as well:

DB_CONNECTION=pgsql
DB_PORT=5432

Error message when missing a .env file

There should be a better error message when there isn't a .env file

Reduce filesize

Currently the app requires a lot of disk space.

• Find out what is causing the big size
• Reduce JS bundle size
• Purge Tailwind classes (if possible)

Asset handling

An important part of managing local environments is being able to handle static assets. For Laravel I want to add support for running NPM scripts but I also want a tighter integration with Laravel Mix. This means I want to add buttons for watching assets, building dev assets once and building production assets.

Handle logs

There should be a screen where you can view the application log

Better auto update

Currently Serve updates automatically without notifying the user. The problem is that it restarts so it can be a jarring experience. The user should be notified and asked if they are ready to install updates

Add 'logs' command to CLI tool

It could be nice to be able to run serve logs inside a project to see the Docker log

Release strategy

Currently release builds are created manually on my machine and attached to a GitHub release. I would like to automate in a CI environment.

Command palette

Add a command palette with commands for all common actions.

This will require to extract actions in to single methods. This will also make it possible to add more keyboard shortcuts

Update database version when changing database type

In project settings it should automatically update the value of the database version field when the database type is changed. It works correctly on the create page.

Create simple CLI / shell script to run commands inside containers

Currently the only way to run commands inside the containers is with docker run and docker exec.

There should be another way to do it easier. It could be a global cli tool that can be installed from inside the app (ala VSCode & Sublime) or it could be a simple serve.sh file that is added to the project.

Some inspiration can be found in Vessels vessel file: https://github.com/shipping-docker/vessel/blob/master/docker-files/vessel

serve composer require laravel/jetstream
serve npm install

Stop reading config file while the project is being created

When a project has the status 'creating' it shouldn't tried to read the config file since it doesn't exist before the project has been created

Check if app exists in launcher

Currently the quick action buttons allows you to open apps like Sublime, GitHub Desktop, a database manager etc.

But there are no checks for whether these apps exist. At the very least an error message should be shown if the app doesn't exist.

Cross-platform commands

The main reason Serve currently only supports macOS is the way commands and processes are run. I would like to find a way to do this in a cross-platform way. A library like shelljs looks promising but it can't run exec in Electron apps. This is a huge issue as we would be limited to run what shelljs has implemented as first-class functions.

After doing a bit of research I see 3 possible solutions:

1. Run shelljs through a custom node docker container (Slow?)
2. Run bash through a custom node docker container (Slow?)
3. Add node as a dependency to the project and point shelljs' execPath to that node binary

Queue handling

Currently you still have to run queue jobs through the terminal. I want to add actions for that in Serve.

Error message for missing .env file

There should be a better error message when there isn't a .env file

Order projects by usage

Currently projects are listed in descending order of creation. It would make sense to order them by the last time a project was started.

Import instructions

When importing an existing Laravel project you need to manually update the .env file to point to the correct db, host etc.

Currently this information isn't shown anywhere

Use ENV variables in docker-compose.yml

Currently the contents of docker-compose.yml is overriden each time a change is made to the project settings. This is a problem is people make custom edits to the file. A solution is to expose all project settings as environment variables and reference those in docker-compose.yml