Setup
- Video Demonstration
- Workspace Location
- Switching Workspaces
- Importing Existing Workspaces
- Applications
- Containers
- Volumes
- Installs
Video Demonstration
Workspace Location
AppIgnition will install any new Laravel applications under ~/AppIgnition/Default Workspace by default. You can modify this if you need to when the extension first loads, or at any time by clicking the Settings link under Default Workspace in the sidenav.
If you modify the workspace's location after installing your applications, you will have to reinstall them to make sure they exist in the new location.
{warning} At this time, it is not possible to modify the name of your Default Workspace since it is used to generate your containers. However, you can create an unlimited number of new workspaces.
Switching Workspaces
In AppIgnition, you can create as many workspaces as you'd like. To do so, click the Switch/New link under your current workspace in the sidenav. You'll be presented with the option to either switch your workspace to an existing one you already created, or create a new one.
Each workspace will have its own associated directory where all of your applications and the container repository to run them will be installed. When switching workspaces, you might want to consider stopping all your containers for your current workspace, as there might be port conflicts when starting containers in your new workspace.
Importing Existing Workspaces
One of the benefits of using AppIgnition is it allows you to quickly onboard with existing projects or onboard new members to your current project. If an application was already installed via AppIgnition, a configuration file would have been generated in the project's directory that defines the containers and other applications associated to it. This can easily be imported into AppIgnition by using its Import feature. You can either start an import when you first load AppIgnition, or you can do it later using the side navigation on the left under your current workspace.
Applications
In most cases, you will only need to install one application in your workspace. However, if you're working with or planning on building a microservice architecture, you can create as many applciations as you'd like. To support this functionality, each application will create an alias that is the camel-case version of your application's name. As an example, My Blog will be accessible on your local machine through my-blog.test. This will require you to edit your hosts file, or you can let AppIgnition take care of it before your installation takes place. The popup below will appear after attempting to install the My Blog application.
There are two methods to create an application in your workspace:
Once you have at least one application configured, you're ready to run your first installation. This will not only setup your application as you have specified, but it will also build all of the containers you have added to your workspace.
Containers
If you're unfamiliar with the concept of containers, I would recommend reading this article from Docker. To provide a brief explanation, containers are built from images that configure and package software so that it can run in an isolated environment on the host's machine. You can have one container to run a database, another to run a web server, or a single one to run them both. The benefit of containerization is that it is an incredibly reliable way to ensure your environment matches not just the same environment as someone else, but also the same as your production environment. Moreover, rather than having to spend hours or days installing and configuring local versions of the software you need to run your application, you can run a container that already has the needed and configured software.
In AppIgnition, you have your choice of several different containers for running databases, web servers, caching servers, queue workers, and database management applications. Each container has a number of configurations, but all of them can be configured within AppIgnition's interface. To get started, I would recommend going through the setup wizard when you first load the extension.
Once you have all of the containers you need, you can build and run them by installing one of your applications. Based on the applications you choose to install, your application will automatically be configured to connect to your containers' services.
Volumes
It's not required for you to know too much about Volumes, but they are Docker's way of mapping a container's directory to a local directory. Through this mechanism is how you're able to install your applications on your host machine while also having them available in your containers. Additionally, this allows you to modify your source code on a container and have those changes propagate to your host machine, and vice versa. All of this will be handled automatically in AppIgnition when you specify your workspace's location. The chosen directory will be mounted as a Volume on all of the containers that require your source code, meaning if you choose to change your workspace's location after installing your applications, you'll have to reinstall them.
Installs
After you have at least one application configured, you're ready to run your first install. You can choose to install one application at a time, or several at once. However, I would recommend running several to prevent having to rebuild your containers' images every time. After you start the installation, you'll be shown an ongoing log for all of the actions being performed on your machine, such as installing your application, building your containers' images, installing your applications' dependencies, and configuring your applications' environments.
This could take about 15-20 minutes depending on how many resources you allocated to docker, how many containers you've added to your workspace, and how many applications you're installing. Once finished, your applications will open on your machine's default browser, so long as you added a web server container. Furthermore, you can always load your applications' URLs after they have been installed if you navigate back to the Dashboard.
As an added benefit of installing your applications through AppIgnition, you'll notice your .env files have already been configured to connect to all of your containers automatically. A .env.testing file will also be created with similar configurations so that you can run your Unit or Feature tests against a different environment.
If at any time you need to reconfigure your apps or containers, or if you need to add another container to your workspace, you can reinstall your applications as many times as you'd like. However, you should first initialize a git repository if you haven't already done so, and then commit your changes since reinstalling your apps might overwrite some of your configuration files. But for now, I'd say you're ready for liftoff! Go build something amazing!