Getting Started

Installation

Getting the code

First you need to install the source code on your local machine or create a new Git repo (in case you want to use Gitpod).

Via Download

The easiest way to get the code is to just download it. Click the code button and select Download Zip or use the following terminal command:

curl https://github.com/joomlatools/joomlatools-server/archive/refs/heads/master.tar.gz | tar -xz

Via Composer

You may also download Joomlatools Server by issuing the Composer create-project command in your terminal:

composer create-project joomlatools/joomlatools-server [directory] --stability dev

For more info: https://getcomposer.org/doc/03-cli.md#create-project

Via Clone

You can also clone the repository using Git by issuing the following command in your terminal:

git clone https://github.com/joomlatools/joomlatools-server

For more info: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository

Via Fork

Finally you can also fork the repository through Github, this can only be done through the Github user interface. For more information: https://docs.github.com/en/get-started/quickstart/fork-a-repo#fork-an-example-repository

Development

Once you have the code the approach you take will depend on what you're trying to achieve at the time:

• Local development? Go with Docker & your own IDE
• Collaborate with others? Use Gitpod
• Deploying live? Go with Fly.io

There are other scenarios of course, and provided you can work with a Docker image, it's likely to work.

Using your own IDE

To develop locally, you will need:

1. Docker Desktop
2. Composer installed globally (not required)
3. A local installation of this repo via one of the methods above
4. Your own IDE
5. Access to a CLI

Once you've completed steps 1 & 2 above, add the local instance to your IDE, then navigate to the root directory of your installation via the CLI.

In the CLI, execute following command:

docker compose up

Then go to http://localhost:8080 in a browser and you should see the Hello World! greeting.

You're now setup for local development.

IMPORTANT: If you pull any changes from the main Joomlatools Server repo, you will need to execute this command in the CLI:

docker compose down --rmi all

Before executing docker compose up to restart the local server.

NOTE: With Joomlatools Server, the cache directory now resides at /volume/[site]/cache - you may need to periodically delete the contents of this directory to see changes made to your local project.

Using Gitpod IDE

Gitpod provides a super simple way to develop with Joomlatools Server using VSCode, straight from the browser. To get started make sure you have a clone or fork this repo, Gitpod offers support for GitHub, GitLab or Bitbucket and either:

1. Install the Gitpod Chrome or Firefox extension and click the Gitpod button in the toolbar.
2. Go to http://gitpod.io#[my-repo-url-goes-here]

You can find all the documentation for Gitpod here: https://www.gitpod.io/docs/

Gitpod Demo: If you want to give this repo a spin in Gitpod, just click this button and off you go.

This is probably not an ideal environment for pure development. It is however the absolute best method to collaborate with other developers, get support for problems with Joomlatools Server, or showcase your work. It makes it very easy to:

1. Quickly and easily test your issue on a fresh instance of Joomlatools Server
2. Quickly publish that test to Gitpod and share it with other users/developers to get help