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

Recommended: Install Spin to your machine

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:

bash vendor/bin/spin

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

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.

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.

cp .env.example .env

Most of the values in the .env file are fine as is. However, may want to update the following values:

• APP_ENV: Set this to local
• APP_DEBUG: Set this to true

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.

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.

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.

spin run php php artisan key:generate

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.

# 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

spin up

Seed your database

Run the command below in a new terminal window while your containers are running.

spin exec php php artisan migrate

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.

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