Contributing

Follow this guide to learn how to get Financial Freedom up and running locally.

Running locally in your development

We encourage you to replicate this on your machine and tinker around with it. Here is how you can run it.

Important notes:

  • We user Docker to run our entire stack. No local services are required.
  • Be sure if you have MAMP, XAMPP, or any other local services running, that you shut them down first. They will conflict with the ports we use.
  • We use Docker Overrides, which allow us to apply overrides on a per environment basis
  • We have a tool called Spin which greatly improves the development experience
  • spin is automatically installed via Composer for this project

Spin is lightweight and only takes up 300kb of space. It's a bash wrapper for Docker compose and dramatically improves the developer experience for Laravel developers regardless if they are running macOS, Windows, and Linux.

If you need help configuring your machine with Docker, follow the instructions provided by Spin.

Learn how to install Docker with Spin →

Alternative: Add Spin as an alias

If prefer to not install Spin to your machine, you can use the version that is installed automatically via Composer. To do that, you will need to run the following command each time you want to use spin:

Run `spin` from Composer

bash vendor/bin/spin

To shorten the command for using the Composer version of Spin, you can create an aliased command:

Create an aliased command for `spin`

alias spin='[ -f node_modules/.bin/spin ] && bash node_modules/.bin/spin || bash vendor/bin/spin'

Add the above line to your ~/.bash_profile or ~/.zshrc file. After saving the changes, source that file or simply close and re-open your terminal before continuing.

Clone the repo

Pull the repo down into and folder of your choice.

Clone the repo

git clone git@github.com:serversideup/financial-freedom.git

Copy over the example env file

Ensure you have a .env file in the root of your project. If you don't, copy over the example file.

Copy over the example env file

cp .env.example .env

Install composer dependencies

Assuming you aliased spin as defined above, run the following commands. If you didn't, you will need to use bash vendor/bin/spin instead of spin.

Install composer dependencies

spin run php composer install

Install Node dependencies

Using spin to run the command will ensure you have the exact version of Node and Yarn that we use.

Install Node dependencies

spin run node yarn install

Generate a new Laravel app key

Create a new Laravel app key. This will be used for encrypting your sessions and other important data.

Generate a new Laravel app key

spin run php php artisan key:generate

Run Database migrations

Create your local SQLite database and run the migrations.

Run Database migrations

spin run php php artisan migrate

Configure hosts file

The server expects a URL of "https://financialfreedom.dev.test". For that to resolve, you can set your local machine hosts file.

Configure hosts file

# For accessing the Financial Freedom locally
127.0.0.1 financialfreedom.dev.test
# For accessing Mailpit locally
127.0.0.1 mailpit.dev.test
# For using Vite in development
127.0.0.1 vite.dev.test

Bring your containers up

Bring your development environment up

spin up

If you're making changes to the front-end

We use InertiaJS as a frontend javascript library. If you are making changes, you will need to run the "dev" process within Node.

Run the "dev" process within Node

spin run node yarn dev

Accessing the application

Once you have the application online, you can register an account at https://financialfreedom.dev.test/register