Skip to content

dev-setup.md

Latest commit

 

History

History
76 lines (55 loc) · 3.45 KB

dev-setup.md

File metadata and controls

76 lines (55 loc) · 3.45 KB

Set up a development instance

If you have any issues regarding your local setup, you can ask the community in our discussions section.

There are several ways to get your development instance up and running - depending on your previous knowledge and host system, you may find one way easier than another.

Option 1: Manual installation

To set up a Träwelling instance you'll need:

  • npm
  • MariaDB or MySQL (SQLite is used for running tests)
  • Composer
  • PHP and the dependencies mentioned in composer.json

A local instance of db-rest v5 is recommended for the connection to HAFAS. Alternatively you can use a public instance (see .env.example).

After setting up these, you can clone the repository and install the project's dependencies:

composer install
npm install
composer run dev # start the development server, assets and queue workers

Now, you can create your own environment configuration:

cp .env.example .env
vi .env

Please change whatever sounds wrong to you. This is also the place to add API keys (e.g. for Mastodon). While you will not need all of those, you can stumble into weird bugs.

Then, generate some application keys and migrate the database to the latest level:

php artisan optimize
php artisan key:generate
php artisan migrate 
#for example data use 
#php artisan db:seed
php artisan passport:install

Use your webserver of choice or the in php included dev server (php artisan serve) to boot the application. You should see the Träwelling homepage at http://localhost:8000.

Additionally, for continuous functionality:

  • Create a cron job to run php artisan schedule:run every minute.
  • Set up a service initiating with php artisan queue:work to handle essential background tasks. Consider creating separate services for the default and webhooks queue if this is a larger installation.

Option 2: Using docker compose

In the root directory of this repository, you can find a docker-compose.yml file which is using the configuration in .env.docker. With a working docker installation, you can start everything you need for backend development with docker compose up -d.

To change frontend resources that need to be compiled (any .scss, .js or .vue file), we expect you to have a working nodejs environment on your system. You can then un-comment the last volume mount in the docker-compose.yml ( see services->app->volumes) and restart the container. On the host system, run npm install and npm run dev to create artefacts with your changes.

You can generate sample data by setting the environment variable SEED_DB: true for the app container. This will seed the database and reset the oauth master keys every time on restart, when the variable is present. The seeder uses some default profile pictures which are stored in public/uploads/avatars in the host system. To see them in the web application, copy them to the avatars folder in the repository root, which is preserved over restarts.

If you are working on scheduled code or with background jobs, you need to restart the worker containers after making code changes. Otherwise, the workers will keep their PHP processes with the old code running.