Skip to main content

Local Development Setup

info

This local setup is ONLY intended for development purposes. DO NOT use this if you want to actually use solidtime, even if you want to run it locally. If just want to use solidtime, please follow the self-hosting guide.

Prerequisites​

Setup​

The local setup is an extended version of Laravel Sail.

To start you need to download or clone the repository f.e. with:

git clone git@github.com:solidtime-io/solidtime.git

After that, execute the following commands inside the project folder:

docker run --rm \
    --pull=always \
    -v "$(pwd)":/opt \
    -w /opt \
    laravelsail/php83-composer:latest \
    bash -c "composer install --ignore-platform-reqs"

cp .env.example .env

Before you can run the application, you need to set up the environment variables in the .env file. Make sure to set the FORWARD_DB_PORT inside your .env file to a port that is not already used by your system.

By default, the PostgreSQL database is set up to run on port 54329 on your host machine, so you can use that port if it is not already in use.

./vendor/bin/sail up -d

./vendor/bin/sail artisan key:generate

./vendor/bin/sail artisan migrate:fresh --seed

./vendor/bin/sail php artisan passport:install

./vendor/bin/sail npm install

./vendor/bin/sail npm run build

Optional: sail Alias

If you want to use the sail command instead of ./vendor/bin/sail, you can add the following alias to your shell configuration file (e.g. .bashrc, .zshrc):

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Setup with Reverse Proxy​

Using a Traefik reverse proxy is currently required for the local development setup to work properly. The docker-compose.yml file already contains configurations for Traefik, but you need to set up the reverse proxy yourself.

You can follow the following this guide to set up the reverse proxy.

Afterward, add the following entries to your /etc/hosts:

127.0.0.1 solidtime.test
127.0.0.1 playwright.solidtime.test
127.0.0.1 vite.solidtime.test
127.0.0.1 mail.solidtime.test

Then restart the Docker containers with:

./vendor/bin/sail down
./vendor/bin/sail up -d

You should now be able to access the application at http://solidtime.test and the Vite server at http://vite.solidtime.test.

CLI tools​

Code formatting​

You can format the PHP code with the following command:

./vendor/bin/sail composer fix

The frontend code can be formatted with:

./vendor/bin/sail npm run lint:fix

Static code analysis​

You can run the static code analysis for the PHP code with:

./vendor/bin/sail composer analyse

Unit tests​

You can run the unit tests with the following command:

./vendor/bin/sail php artisan test

If you want to run only some test you can use the --filter option:

./vendor/bin/sail php artisan test --filter SomeTestName

If you want to run all test as fast as possible, for example right before a commit, you can use this command:

./vendor/bin/sail composer ptest

Generate ZOD Client​

The Zodius HTTP client is generated using the following command:

npm run zod:generate

E2E Tests​

Running E2E Tests​

./vendor/bin/sail up -d will automatically start a Playwright UI server that you can access at https://playwright.solidtime.test. Make sure that you use HTTPS otherwise the resources will not be loaded correctly.

Recording E2E Tests​

To record E2E tests, you need to install and execute playwright locally (outside the Docker container) using:

npx playwright install
npx playwright codegen solidtime.test

E2E Troubleshooting​

If E2E tests are not working at all, make sure you do not have the Vite server running and just run npm run build to update the version. If the E2E tests are not working consistently and fail with a timeout during the authentication, you might want to delete the test-results/.auth directory to force new test accounts to be created.