Configurable LAMP or LEMP stack starter project powered by Laravel and Gitpod. Supports Laravel 6, 7, and 8. Out of the box support for React, Vue, and Bootstrap frontends, with or without built-in auth .
🚀
gitpod-laravel-starter
generates a starting point for you to develop in the cloud with Laravel web application framework, MySql and pretty much any other technology you would like to add.
If you want to jump right in to setting up a project then have a look at the wiki setup page.
The wiki is designed to provide you with essential details not found in this document such as how to easily add hot reloading and Typescript to your projects.
gitpod-laravel-starter
is designed for any type of developer from beginner to professional to hobbyist. Developing in the cloud has many benefits including giving developers the freedom to try entire complex technological stacks with a single click.
A GitHub account. You may use a free account.
A GitPod account. You may use a free account. Just log in with your github credentials.
There are many ways that you can use gitpod-laravel-starter
. Full setup instructions can be found on the wiki setup page.
Gitpod makes this easy. One simple URL deploys the entire system.
A detailed breakdown of the initialization phase can be found on the wiki initialization page
Initializing the workspace will take between 2 to 5 minutes depending on how you have configured the starter.ini
file. Subsequent starts or creation of a workspace from your repository will be much faster thanks to caching mechanisms.
When the workspace is created for the first time an entire online development environment complete with an IDE is deployed along with any additional installations you have set in starter.ini
. Laravel scaffolding files and debugging capabilities are created the first time you build the workspace so you should push any new files to your repository before you get started developing your project. You can push the files with a single command: git new "Initial Commit"
A preview browser should automatically open and display the Laravel start page once the system is ready. This page is served by the default web server which is set in starter.ini
. The code for the Laravel start page page is in /resources/views/welcome.blade.php
. To manually open the preview browser or to refresh it you can run the command op
.
If the result log summary in the console shows success, then you should push those newly created Laravel scaffolding files to your remote repository before you get started coding your project.
You may need to allow Gitpod additional permissions to push to your repository in case you come across an issue like this one.
If your GitHub account uses the protected email feature and the email address you are using in your git configuration looks something like this:
you may encounter an error that looks something like this:
! [remote rejected] readme-dev -> readme-dev (push declined due to email privacy restrictions)
The easiest way to circumvent error is to uncheck the box labeled "Block command line pushes that expose my email" under Settings-->Emails in your GitHub account.
Another workaround is to edit the ~/.gitconfig
file in your Gitpod workspace to use your protected email address since Gitpod defaults to using the unprotected email address for your GitHub account. Please note that if you do this you will have to make this change for every time you create a new workspace.
A configuration file has been provided to allow you to control many aspects of the development environment and the Laravel project scaffolding.
The file starter.ini
in the root of the project allows you to configure optional installations and other various options. Have a look at the comments in starter.ini
for details and acceptable values you can use. Simply change values in starter.ini
, push those changes to your repository, create a new Gitpod workspace from that repository and your new configurations will be enabled. Some of the configurations you can make are:
apache
, nginx
or php
(development server)phpMyAdmin
react
, vue
or plain bootstrap
tail
with colorized log or multitail
.editorconfig
: You can omit this file or use a less opinionated version of this file than what Laravel gives you by defaultPlease note that a project's package.json can supercede any installation directives that have been set to zero in starter.ini.
Also please note that many of the configurations found in starter.ini
should be made just once prior to creating your workspace for the first time. Have a look at the comments in starter.ini
for specifics.
gitpod-laravel-starter
preset examples are auto-configured examples of React and Vue projects that you can learn from or use as starting points for your own projects.
You can initialize a preset example as a starting point by adding EXAMPLE=<id>
to the Gitpod URL right after the #
and followed by a /
.
To use a preset example as a starting point:
starter.ini
such as phpmyadmin
will not be supercded on subsequent initializations of your workspace. Edit your starter.ini
as needed.id | Description | Workspace URL |
---|---|---|
1 | React Example with phpMyAdmin - Questions and Answers | https://gitpod.io/#EXAMPLE=1/https://github.com/apolopena/gitpod-laravel-starter |
2 | React Example without phpMyAdmin - Questions and Answers | https://gitpod.io/#EXAMPLE=2/https://github.com/apolopena/gitpod-laravel-starter |
3 * | React Typescript Example with phpMyAdmin - Questions and Answers | https://gitpod.io/#EXAMPLE=3/https://github.com/apolopena/gitpod-laravel-starter |
4 * | React Typescript Example without phpMyAdmin - Questions and Answers | https://gitpod.io/#EXAMPLE=4/https://github.com/apolopena/gitpod-laravel-starter |
10 ** | Vue Example with phpMyAdmin - Material Dashboard | https://gitpod.io/#EXAMPLE=10/https://github.com/apolopena/gitpod-laravel-starter |
11 ** | Vue Example without phpMyAdmin - Material Dashboard | https://gitpod.io/#EXAMPLE=11/https://github.com/apolopena/gitpod-laravel-starter |
* Comes with hot reload functionality
** Not designed to run in an iframe such as the preview browser in the IDE.
gitpod-laravel-starter
project comes pre-packaged with three development servers that serve on the following ports:
php-fpm
): port 8002By default the server set in starter.ini
will be the server used. You can run any server at the same time or change your default server in starter.ini
at any time.
Please note that Laravel uses the APP_URL and ASSET_URL variables set in .env
to serve content. These values are set during workspace initialization and are based on the default server you are using. If you want serve the project using a different server after a workspace has been created, then you will need to change APP_URL and ASSET_URL in .env
to have the port number in it for the server you want to use.
You may also run the PHP Development server manually via the command php artisan serve
which will use port 8000.
The default server will be started automatically when the workspace is started.
You can toggle any server on and off from any terminal window by running the relevant command. These commands will also dynamically kill the log monitor process for that server:
start_apache
or stop_apache
start_nginx
or stop_nginx
start_php_dev
or stop_php_dev
Change the value of default_server
in the development
section of starter.ini
to apache
, nginx
, or php
. You will need to change the APP_URL and ASSET_URL in the .env
file to use the port number for that server if you change the default development server after a workspace has been created.
You may start and stop multiple servers.
If you have the Apache server running and you want to run the Nginx server at the same time just run this command:
start_nginx
The Nginx server will now be running in addition to the Apache server.
Laravel requires a URL to be set in the .env
file in the project root. This is done for you automatically when the workspace is initialized. The URL set in the .env
file contains the server port. so if you want to properly serve Laravel pages from a server other than the default server you initialized the project with then will need to change the values for APP_URL and ASSET_URL accordingly.
In starter.ini
there is a [PHP]
section and directives to change the version of PHP and or the ppa
used for downloading the PHP packages.
Note: See starter.ini
for more details.
The following values are supported in the [PHP]
section of starter.ini
:
version
7.4
workspace-full
image will be automatically purged.gitpodlatest
workspace-full
image.ppa
OS
ondrej
ppa:ondrej/php
. This ppa is maintained by an individual but does support the of running multiple versions of PHP side by side.In starter.ini
there is a directive to change the version of Laravel. You should only change the version of Larvel before you create a new workspace. The laravel version directive is cached in the workspace image so changing it sometimes requires you to break the Docker cache
Important:
gitpod-laravel-starter
uses the most recent version of Laravel. Currently the most recent version of Laravel is 8.*
8.*
, 7.*
, and 6.*
Caveats:
You can break the Docker cache and force the workspace image to be rebuilt by incrementing the INVALIDATE_CACHE
variable in .gitpod.Dockerfile
. Push the changed .gitpod.Dockerfile
to your repository, create a new gitpod workspace and the workspace image will be rebuilt. Any cached external files that Docker uses such as starter.ini
will be updated.
The following features can be enabled through environment variables that have been set in your Gitpod preferences.:
* Please note that storing sensitive data in environment variables is not ultimately secure but should be OK for most development situations.
GPG_KEY_ID
(required)
GPG_KEY
(required)
GPG_KEY_ID
GPG_MATCH_GIT_TO_EMAIL
(optional)
~/.gitconfig
to the value providedGPG_AUTO_ULTIMATE_TRUST
(optional)
yes
or YES
then your GPG_KEY
will be automatically ultimately trustedINTELEPHENSE_LICENSEKEY
~/intelephense/licence.txt
and will contain the value providedTo keep the gitpod-laravel-framework
as flexible as possible, some features have been left out of the starter.ini
configuration file. These additional features can be easily added to your project using a one-time set up process. Wiki pages are available for each additional feature below that you may want to add to your project. Some of these features are automatically enabled for certain preset examples.
gitpod-laravel-starter
makes it easy for you to add the ability to see your code changes in realtime without refreshing the browser. Take a look at the wiki hot reload page for more details.Debugging must be enabled before breakpoints can be hit and will last for an hour before the debug session is disabled automatically.
When debugging is enabled or disabled, the preview browser will reload the index page. When debugging is enabled, each subsequent request can be debugged for an hour or until debugging is disabled.
This system uses port 9009
for the debugging. A launch configuration file is included in .vscode/launch.json
and in .theia/launch.json
.
To enable a debugging session on the default development server run debug_on
in a Gitpod terminal.
To disable a debugging session on the default development server run debug_off
in a Gitpod terminal.
You can toggle a debugging session for a specific server:
debug_on apache
or debug_off apache
debug_on nginx
or debug_off nginx
debug_on php
or debug_off php
The hot reload webpack server on port 3005 is not supported by this debugging system. You may be able to configure it on your own if you like.
Set a breakpoint in the Gitpod IDE by clicking in the gutter next to the line of code you want in any PHP file in the public
folder (or deeper)
Then in the Gitpod IDE in the browser:
op
command and your breakpoint will be hit in the IDE.All debugging is subject to a server timeout, just refresh preview browser or run the command op
if this happens.
You may also debug blade templates by placing the following snippet above where you want to inspect the blade directive.
<?php xdebug_break(); ?>
Save the file and refresh the preview browser when the debugger is in the IDE.
This will open a temporary PHP file that has all the blade directives converted to php
tags, you may set additional breakpoints in this code as well. Do not edit the code in these temporary files as it they be disposed at any time and are only derived for the current debugging session.
If you are having trouble, launch the "Listen for Xdebug" launch configuration again and refresh the preview browser.
You may want to see how Xdebug is working with your server when you are debugging PHP files.
tail -f /var/log/xdebug.log
The is a rather diverse topic. To make a long story short it is possible but very situational.
Have a look at the wiki debugging JavaScript page for details and exact steps you can take to debug various types of JavaScript.
phpMyAdmin is a tool that handles MySQL administration over the web. This tool is very powerful and can be essential when developing MySQL powered systems especially in the cloud. For more information on what phpMyAdmin can do, check out the official documentation, the user guide or just dabble around on the demo server.
phpMyAdmin is installed automatically by default. A phpMyAdmin installation directive is available in starter.ini
that allows you to omit the installation if you like.
phpMyAdmin also introduces some extra security concerns that you may want to address. If you have installed phpMyAdmin using the install directive in starter.ini
then by default, two MySQL accounts are created using default passwords stored in version control:
phpmyadmin
database and should not be used by anyone.
At a minimum the default passwords that phpMyAdmin uses to administer the MySQL databases should be changed right after a Gitpod workspace has been created for the first time. An update-phpmyadmin-pws
command has been provided that automagically changes the default passwords for you.
The following steps are required to successfully run the update-phpmyadmin-pws
command:
.starter.env
. You can run this command from the project root: cp .gp/.starter.env.example .gp/.starter.env
PHPMYADMIN
from .gp/.starter.env.example
to your blank .starter.env
file.starter.env
, set your password values for the PHPMYADMIN
keys and save the fileupdate-phpmyadmin-pws
Keeping track of your changes and releases can easily be automated.
There is an option in starter-ini
to install github-changelog-generator
.
This option is on by default and additional settings for this option can be found in starter.ini
.
You can generate a CHANGELOG.md
by running the command:
rake changelog
Currently generating a changelog can only be done when the workspace is built for the first time. See here for more details. See github-changelog-generator for documentation.
GitHub limits API calls unless using an access token.
github-changelog-generator
uses the GitHub API to generate a CHANGELOG.md
and will quickly max out of API calls if you try to generate the CHANGELOG.md
more than a few times in a certain period of time.
It is recommended that you setup an access token from your GitHub account and then set that access token in an environment variable via your Gitpod dashboard. This way any project you like can generate a CHANGELOG.md
as many times as it likes without error.
CHANGELOG_GITHUB_TOKEN
github-changelog-generator
via the rake changelog
command as many times as you like.Important Note: If you do not generate an access token for github-changelog-generator
, and if you do not cancel the error that results when you exceed your Github API calls when using github-changelog-generator
then you could potentially run out of space for your github workspaces and not be able to create any any new workspace or open any existing ones until you delete the offending workspace(s) or the system is cleared automatically.
Most of the files in gitpod-laravel-starter
are core files and should not be altered unless you open PR for gitpod-laravel-starter
however some files are provided so that you can customize your project even further.
You are encouraged to put your project specific code in files mentioned below:
.gp/bash/init-project.sh
.gp/bash/install-project-packages.sh
apt-get
) when the docker image layers are built can be added as a single space delimited string to this file..gp/bash/install-project-packages.sh
will require a rebuild of the Docker image layers before the workspace is created for the first time.INVALIDATE_CACHE
value in .gitpod/Dockerfile
and push that change to the remote repositoryIt is recommended that you migrate and seed your project in this file: .gp/bash/init-project.sh
.
For example, the react preset makes use of .gp/bash/init-project
for migration and seeding.
Currently until gitpod fixes the issue of ruby gems not persisting across workspace restarts, you can only use rake commands when the workspace is created for the first time.
Git aliases that you would like to add to your project should be added to the alias
file.
A compilation of git aliases from Emoji-log and Gitmoji are included, use them as you like from the command line. There is also a separate set of emoji based git aliases that will commit the files with a message and push them to the repository without adding the files. Use these aliases for dealing with groups of files that need different commit messages but still need to use to Emoji-log and or Gitmoji standards. You can get a list of all the emoji based git aliases with the command: git a
For now this will be something you need to figure out, eventually some guidelines for how to do that may be added here.
Gitpod is an amazing and dynamic platform however sometimes during it's peak hours, latency can affect the workspace. Here are a few symptoms and their possible remedies. This section will be updated or removed as Gitpod evolves.
You can also try to remedy any rare Gitpod network hiccups by simply waiting 30 minutes and trying again.
🙏 to the communities of: