Py2Json26

Py2Json26 is an app to convert Python dictionaries to JSON format. Py2Json26 is built with...

• Laravel 12
• TailwindCSS v4
• Livewire 4
• PestPHP 4 for testing
• FluxUi components

Contents

• Requirements
• Paid Dependencies
• Environment Variables
• Get started with Docker (locally)
  • Build and run with Docker Compose
  • Database
• Getting started locally (without Docker)
• GitHub Actions
  • CI Workflow (ci.yaml)
  • CD Workflow (cd.yaml)
• Testing
  • Running all tests
  • Running tests and updating snapshots
• Useful notes and commands
  • Building the Docker image manually
  • Trusted proxies

Requirements

• PHP 8.3+
• Composer
• NodeJS 20+
• Docker (optional, for building images)

Paid Dependencies

Py2Json uses FluxUi pro components for the user interface. This is a paid package and a license is required to install the components from their private repository.

If you have a license you can create an auth.json file with your credentials. See Flux documentation for more details.

use the following command to generate an empty auth.json file:

php artisan flux:activate

if you have already setup an auth.json file you can install the flux pro components with:

composer require livewire/flux-pro

Environment Variables

Laravel uses environment variables to configure various aspects of the application. Most of the defaults are set in the .env.example file. You can copy this file to .env and modify it as needed.

To disable stack traces in browser set APP_DEBUG=false in your .env file.

Get started with Docker (locally)

Licence: Ensure you have an auth.json file with a valid license to install paid dependencies see Paid Dependencies

Build and run with Docker Compose

The following command will build and start the application using Docker Compose:

DOCKER_BUILDKIT=1 docker compose up --build

Visit http://127.0.0.1:8000 in your web browser to access the application.

Database

This will use a sqlite in memory database, so any data will be lost when the container is stopped. To avoid this modify the docker-compose.yml file to use a persistent database.

Getting started locally (without Docker)

1. Install PHP dependencies using Composer

   Licence: Some dependencies require a valid license and auth.json file to install correctly see Paid Dependencies

   composer install

2. Install JavaScript dependencies using npm, or Bun

   npm install
   # or
   bun install

3. Copy the example environment file and configure your environment variables

   cp .env.example .env

4. Generate an application key (APP_KEY) (if not already done)

   php artisan key:generate

5. Run database migrations

   php artisan migrate

6. Start Vite development server

   npm run dev
   # or
   bun run dev

7. Start the Laravel development server

   php artisan serve

GitHub Actions

The project includes two Github Actions workflows for CI/CD.

ci.yaml

This workflow runs on every pull request to the main branch. It will...

1. Check you have updated the project version in composer.json
2. Run all the Pest tests (excluding screenshot diff tests)

Playwright: If you need to install the Playwright browsers uncomment the lines in the ci.yaml file.

Secrets

This workflow expects the following secrets to be set in the Testing environment of your repository settings:

1. FLUX_USERNAME - The email address associated with your FluxUi account
2. FLUX_LICENSE_KEY - Your FluxUi license key

cd.yaml

This workflow runs on every push to the main branch. It will...

1. Build and push a Docker image to GitHub Container Registry
2. Deploy the app to a CapRover server

Secrets

This workflow expects the following secrets to be set in the Production environment of your repository settings:

1. COMPOSER_AUTH - The contents of your auth.json file for installing paid dependencies, note this secret MUST be a single line JSON string otherwise the workflow will fail.
2. CAP_SERVER_URL - The base URL of your CapRover server e.g https://captain.yourdomain.com
3. CAP_APP_NAME - The name of the app on your CapRover server e.g py2json
4. CAP_APP_TOKEN - The token for your CapRover app

Testing

Py2Json uses PestPHP for testing. Tests are split into Feature and Unit tests located in the tests/Feature and tests/Unit directories respectively.

Running all tests

php artisan test --parallel

Useful notes and commands

Building the Docker image manually

Build the docker image with secret auth.json manually ...

DOCKER_BUILDKIT=1
docker build \
  --secret id=composer_auth,src=auth.json \
  -t py2json .

Trusted proxies

Py2Json is currently configured to trust all proxies by default. If you need to restrict this, you can modify the bootstrap/app.php trustProxies method.

TODO

• Install python in Docker image