Install Trama with Docker

Prerequisites

• Docker Desktop, or Docker Engine with the Compose plugin.
• At least 4 GB of free RAM.
• These free ports on the host:

Quick install

Seven steps, the same as in the README. Run the commands in the folder where you want to install Trama.

1. 1

   Step 1: Clone the repository

   $ git clone https://github.com/lejubila/trama-dev.git trama
   $ cd trama

2. 2

   Step 2: Configure the environment

   The second command matches the container user to the owner of the folder: without it, composer and npm can't write vendor/ and node_modules/.

   $ cp .env.example .env
   $ sed -i "s/^TRAMA_UID=.*/TRAMA_UID=$(id -u)/; s/^TRAMA_GID=.*/TRAMA_GID=$(id -g)/" .env

3. 3

   Step 3: Start the containers

   The first run builds the application image and takes a few minutes.

   $ docker compose up -d --build

4. 4

   Step 4: Install the PHP dependencies

   $ docker compose exec app composer install

5. 5

   Step 5: Generate the key and set up the database

   --seed loads the sample data: example customers and the three users listed below.

   $ docker compose exec app php artisan key:generate
   $ docker compose exec app php artisan migrate --seed

6. 6

   Step 6: Link the uploads folder

   Creates the public/storage → storage/app/public link used for photos, floor plans and icons.

   $ docker compose exec app php artisan storage:link

7. 7

   Step 7: Build the front end

   While developing, use docker compose exec app npm run dev instead of npm run build.

   $ docker compose exec app npm install
   $ docker compose exec app npm run build

First login

Open http://localhost:8081 and sign in with one of the sample users. Emails sent by Trama never leave your machine: you'll find them in Mailpit at http://localhost:8025.

Troubleshooting

vendor does not exist and could not be created, or permission denied

The same problem can show up as permission denied on storage/ or node_modules/. Commands in the container run as the app user, with UID and GID taken from TRAMA_UID and TRAMA_GID in .env (default 1000). They must match the owner of the project folder on the host.

1. Compare the folder owner with your user.

   $ ls -ldn .          # UID and GID owning the folder
   $ id -u; id -g       # your UID and GID

2. Set TRAMA_UID and TRAMA_GID in .env to those values, then rebuild the images.

   $ docker compose build app scheduler && docker compose up -d

3. If the folder was cloned as root, take ownership of it first.

   $ sudo chown -R $(id -u):$(id -g) .

A port is already in use

If docker compose up reports that a port is already allocated, change the matching TRAMA_*_PORT variable in .env (see Prerequisites) and run docker compose up -d again.

Useful commands

$ docker compose exec app bash

$ docker compose exec app php artisan tinker

$ docker compose exec app php artisan test

$ docker compose exec app ./vendor/bin/pint

$ docker compose exec app ./vendor/bin/phpstan analyse

$ docker compose exec app php artisan queue:work

$ docker compose exec app php artisan migrate:fresh --seed

$ docker compose exec app php artisan icons:defaults

$ docker compose exec app php artisan icons:defaults --export

Running a public demo

Trama can run as a public demo: visitors sign in with one click, change the data (except users) and every day everything goes back to its initial state. That's how demo.tramanet.work works.

1. 1

   Step 1: Prepare the data

   Create a curated sample customer, locally if you like, with photos, floor plans, Wi-Fi, VPNs, documents and snapshots, and export it from Customers → Export data. Put the .zip in database/demo/: every archive there becomes a demo customer.

2. 2

   Step 2: Configure .env on the demo server

   APP_ENV=production
   APP_DEBUG=false
   MAIL_MAILER=log
   DEMO_MODE=true
   [email protected]
   DEMO_USER_PASSWORD=demo
   DEMO_RESET_TIME=03:00
   DEMO_TIMEZONE=Europe/Rome
   
   # If the default ports are taken on the host:
   APP_URL=http://your-host:8083
   SANCTUM_STATEFUL_DOMAINS=your-host:8083
   TRAMA_HTTP_PORT=8083
   TRAMA_REDIS_PORT=6380

3. 3

   Step 3: Start the scheduler and load the data for the first time

   From then on the scheduler container repeats the reset every day at DEMO_RESET_TIME, in the DEMO_TIMEZONE time zone.

   $ docker compose up -d scheduler
   $ docker compose exec app php artisan demo:reset

What changes in demo mode

• The sign-in page shows the “Enter the demo” button and the credentials.
• A banner on every page warns about the daily reset, with a countdown; after a reset a notice appears.
• User management, profile, email and password changes, account deletion, API tokens, assigning users to customers and password recovery are disabled.
• Language and active customer are stored in each visitor's session, because the demo account is shared.

Upgrading

1. 1

   Step 1: Back up the database

   $ docker compose exec -T postgres pg_dump -U trama trama > trama-backup.sql

2. 2

   Step 2: Get the new version

   $ git pull

3. 3

   Step 3: Rebuild and restart the containers

   Needed in case the application image has changed.

   $ docker compose up -d --build

4. 4

   Step 4: Update dependencies, database and front end

   With APP_ENV=production, migrate asks for confirmation before running.

   $ docker compose exec app composer install
   $ docker compose exec app php artisan migrate
   $ docker compose exec app npm install
   $ docker compose exec app npm run build

To add any new default icons without touching customised ones, also run docker compose exec app php artisan icons:defaults.