Miscellany is a collaborative world building and campaign management tool tailored for tabletop RPG players and game masters.
After cloning the project, create the following files.
.env
cp .env.example .env
- You'll need to fill it out to your needs.
public/.htaccess
- If on Apache. You can run
cp .htaccess.example public/.htaccess
for quick development on docker.
- If on Apache. You can run
Make sure you have composer, Vagrant and their dependencies installed and walk through the next steps:
Run command composer install
- This will install all PHP-dependencies of the project
Then for Mac/Linux users, run:
php vendor/bin/homestead make
For Windows users, run:
vendor\\bin\\homestead make
Now you can run vagrant up
to start your virtualized local dev environment.
For more information on Laravel Homestead check this link. We currently use the per-project installation.
You should now be able to vagrant ssh
into your virtual machine.
Run the commands below after changing directory to code
.
php artisan key:generate
php artisan storage:link
php artisan voyager:install
php artisan migrate
php artisan db:seed
That should cover you. You can now create an account. If you have errors on the dashboard, check that your roles
table has entries, and that your user has a valid role_id
value.
follow the step given above for creating the .env file, then modify it by deleting the following:
DB_HOST=mysql
Now add the following lines to your .env file:
# Docker
DOCKER_WEB_PORT=8000
DOCKER_MYSQL_PORT=3306
Start he containers by issuing the following command:
> docker-compose up -d --build
Note that the output stops before the web container is finished with everything that it needs to do so it may appear that everything is ready before you'll get a response from localhost in your browser. You can check the logs to see the status of the scripts that are run once the container is up.
docker-container logs -t
The app revolves around the concept of Entities
. This are for example:
- Characters
- Items
- Locations
Each entity is split between two tables:
- The
entity
table which contains some generic information available to all entities (name, id) - A table for the specific data of the entity.
Most entities can have n-to-n relations to other entities.
For example, there are Relations
that link two entities together, as well as Attributes
which contains n-to-1 custom data of an entity.
Assets can be compiled by following the Laravel Documentation
You'll need to install the various npm packages first.
npm install
Select2 needs to be forced to 4.0.5 because newer builds (4.0.7) break
npm install select2@4.0.5 --save
The following will produce assets for development
npm run dev
The following will produce assets for production
npm run prod
The following rules apply when developing the application.
All improvement, feature or bug must be related to a ticket on github. Each commit must contain on the first row the name and ticket id of the issue related to the change.
Code must follow PSR-4 recommendations.
All migrations should have a working down()
function. Exceptions are allowed for migrations that alter lots of content.
Development should be done on your own fork of the repository in the develop
branch, with substantial new features done in a separate branch.
Tagging is only done on the master branch.
Once a feature is ready and tested, the admin will merge it into the master branch. There is no auto-deploy to the servers.
To work on translations, execute the following command to clean you translations and re-import them.
php artisan translations:reset
php artisan translations:import
In the database, change your user's is_translator
to true
._Navigate to /translations
to start working on your translations. Add your new language to app/config/laravel-translation-manager.php
if needed.
When you are finished, export your changes.
php artisan translations:export *
To backup your database in a gzip file, Kanka uses the laravel backup manager execute the following command (adapt to your config)
php artisan db:backup --database=mysql --destination=s3 --compression=gzip --destinationPath=prod/ --timestamp="d-m-Y"
To restore a db, use the following
php artisan db:restore
The configuration for PHPUnit-Tests is in the file /phpunit.xml. Before the first run you have to run
php artisan setupTestDB --env=testing
to create and setUp the TestDatabase. Also if the Database-Schema changes or new migrations are added, you have to reset the Testing Database with this command.
The Configuration for the TestEnvironment can be found in the File /phpunit.xml and .env.testing. The Environment-Variables in both files need to be the same.
If everything is setup correctly you can run the tests by just calling
phpunit
in the project directory.