Skip to content

Latest commit

 

History

History
209 lines (144 loc) · 6.27 KB

INSTALLATION.md

File metadata and controls

209 lines (144 loc) · 6.27 KB
Raw

INSTALLATION

This documentation describes, how you can install this project.

Getting started

Requirements

See the Requirements section in the main README.

Clone repository

First of all, you need to clone this project on your web server:

# install it in any directory, where you want
cd /var/www/
git clone https://github.com/Sebbo94BY/teamspeak-dynamic-banner.git

Checkout a specific version

Next, checkout a specific version of this project.

Switch into the project directory:

cd teamspeak-dynamic-banner

Checkout the latest version:

git checkout $(git tag | tail -1)

Install dependencies

Install the dependencies:

cd laravel/
npm install --omit=dev
npm run build
composer install --optimize-autoloader --no-dev

Configure and prepare the application

Generate an unique application key:

php artisan key:generate

Edit the .env file to your needs:

  • APP_NAME: The name of this application (only shown in the browsers tab)
  • APP_ENV: Based on the environment, some implementations may work different (e.g. more or less logging, more or less schedules, ...)
    • testing: For PHPUnit tests only
    • local: For local development using the here provided Docker setup use only
    • staging: For testing/staging use only
    • production: For production use only
  • APP_KEY: This should be set automatically by the composer install command.
    • Backup this key. It's used for encrypting and decrypting secrets in the database.
    • NEVER ever share this with anyone else!
  • APP_DEBUG: Should be false in testing/staging and production as it reveals sensitive data such as passwords.
  • APP_URL: The base URL of your application (mainly for setting the correct URL in e.g. password reset emails).
  • DB_*: Database connection settings
  • REDIS_*: Redis connection settings
  • MAIL_*: SMPT settings for sending emails (e.g. password reset email)

Cache and optimize the application:

php artisan optimize
php artisan view:cache

Install the database schemas:

php artisan migrate

Seed the database with the necessary defaults:

php artisan db:seed

Grant the web server user (e.g. www-data) the necessary permissions:

chown www-data:www-data -R teamspeak-dynamic-banner/

Setup Scheduling

For the scheduling, you need to set up a regular cronjob, which runs every minute. The application itself takes care about how often which task should run.

  1. Create a new cron file (e.g. /etc/cron.d/teamspeak-dynamic-banner)

  2. Insert the following configuration:

    * * * * * www-data cd /var/www/teamspeak-dynamic-banner/laravel/ && /usr/bin/php artisan schedule:run >> storage/logs/scheduler.log 2>&1

  3. Adjust the user and directory to your requirements

  4. Save the file

You can verify, if the scheduling works as expected when it automatically creates the scheduler.log with some output.

Setup Queue

For the queue, you probably want to set up Supervisor, which automatically monitors your queue processes and restarts them, if necessary.

  1. Install the respective Supervisor package: sudo apt-get install supervisor

  2. Create a new Supervisor config file (e.g. /etc/supervisor/conf.d/teamspeak-dynamic-banner.conf) with the following content:

    [program:teamspeak-dynamic-banner-worker]
process_name=%(program_name)s_%(process_num)02d
directory=/var/www/teamspeak-dynamic-banner/laravel
command=/usr/bin/php artisan queue:work --queue default --timeout 10 --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=8
redirect_stderr=true
stdout_logfile=/var/www/teamspeak-dynamic-banner/laravel/storage/logs/worker.log
stopwaitsecs=3600

  3. Save the file

  4. Reread the Supervisor config: sudo supervisorctl reread

  5. Update the Supervisor config: sudo supervisorctl update

  6. Start the workers: sudo supervisorctl start teamspeak-dynamic-banner-worker:*

  7. Ensure, that the workers are running: supervisorctl status teamspeak-dynamic-banner-worker:*

You can verify, if it's working as expected, when you later upload your first templates. Those get processed by the queue:

$ cat /var/www/teamspeak-dynamic-banner/laravel/storage/logs/worker.log
  [...]
  2023-03-13 20:50:34 App\Jobs\DrawGridSystemOnTemplate .............. RUNNING
  2023-03-13 20:50:34 App\Jobs\DrawGridSystemOnTemplate .............. RUNNING
  2023-03-13 20:50:34 App\Jobs\DrawGridSystemOnTemplate .............. RUNNING
  2023-03-13 20:50:34 App\Jobs\DrawGridSystemOnTemplate .............. RUNNING
  2023-03-13 20:50:34 App\Jobs\DrawGridSystemOnTemplate ........ 251.57ms DONE
  [...]

Setup web server virtual host

HINT

If your TeamSpeak server is reachable via IPv4 and IPv6, the API endpoint of this application should be also reachable via both.

Otherwise, clients connected with IPv6 to your TeamSpeak server will connect with IPv4 to the API of this application and then no matching client will be found.

Setup a virtual host for this web application and point the root directory to the project laravel/public directory.

In this documentation, it would be for example /var/www/teamspeak-dynamic-banner/laravel/public.

After enabling this virtual host, the web application should be available at the specified domain and show you the install wizard.

First Steps

After you have completed the install wizard, you will see the dashboard of the application.

It is recommended to open the Administration > System Status page in order to check, if everything is operational or needs attention.

Your next steps should be the following:

  1. Download and install one or more TrueType Fonts as explained under Administration > Fonts
  2. Add and configure an instance
  3. Start the newly created instance
  4. Upload one or more templates
  5. Add a new banner configuration
  6. Add one or more recently uploaded templates to the banner configuration
  7. Configure your templates for your banner with some texts
  8. Configure the banner API URL in your TeamSpeak server as Hostbanner Gfx URL
  9. Enjoy your dynamic banner :-)