diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/404.html b/404.html new file mode 100644 index 00000000..059b89bb --- /dev/null +++ b/404.html @@ -0,0 +1,1258 @@ + + + + + + + + + + + + + + + + + + + + SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ +

404 - Not found

+ +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/about/contact/index.html b/about/contact/index.html new file mode 100644 index 00000000..164c0c6d --- /dev/null +++ b/about/contact/index.html @@ -0,0 +1,1349 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Contact - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Contact

+

Have a question? Want to say thank you? Need to express your opinion on SeAT? You are welcome to join us on our official Discord Server! https://discord.gg/VcUZRcnMYK.

+ + +

EVE Online Forum Thread

+

Track the conversation on the EVE Online Forums.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/about/reporting_bugs/index.html b/about/reporting_bugs/index.html new file mode 100644 index 00000000..0660b18a --- /dev/null +++ b/about/reporting_bugs/index.html @@ -0,0 +1,1397 @@ + + + + + + + + + + + + + + + + + + + + + + + + Reporting Bugs - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Reporting Bugs

+

So, you think its time to report an issue. Awesome! However, before you do this, please go through the troubleshooting steps first to identify any common errors that you might be able to to fix yourself.

+

The more info, the better

+

In order to best understand the bug, we need as much info as possible about your environment. For that, you can run the following command (from your SeAT directory), and copy / paste the output as part of your bug report:

+
php artisan seat:admin:diagnose
+
+

Log files

+

Log files are a fantastic resource. Check out the Laravel log for any Exception type errors, and add them to your bug report. The log file is located (relative to where you installed SeAT) at:

+
storage/logs/laravel-<todays-date>.log
+
+

Screenshots and debug mode

+

Screenshots may also help, so don't be shy to take some and attach them to your bug report! If you flip your installation into debug mode then it may be possible to capture the error that is occurring via a screenshot.

+

Report the bug

+

Finally, to report the bug, head over to Github Issues and click on New Issue.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/admin_login/index.html b/admin_guides/admin_login/index.html new file mode 100644 index 00000000..47bd5430 --- /dev/null +++ b/admin_guides/admin_login/index.html @@ -0,0 +1,1351 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Admin Login - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Admin Login

+

SeAT is heavily relaying on EVE Online Single Sign-On to authenticate user. +However, it's also shipped with a built-in administrator user.

+

You need an admin account in order to do certain tasks like configuring your instances, roles, squads, etc...

+

In order to authenticate with built-in admin user, use command disclosed bellow (choose your context).

+
+
+
+
1
+2
cd /opt/seat-docker
+docker-compose exec seat-web php artisan seat:admin:login
+
+
+
+
1
+2
cd /opt/seat-docker
+docker compose exec front php artisan seat:admin:login
+
+
+
+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:admin:login'
+
+
+
+
+

You'll get a link after the command has finished running, which looks similar to the one bellow:

+
1
+2
+3
+4
+5
+6
+7
+8
SeAT Admin Login URL Generator
+User 'admin' does not exist. It will be created.
+Checking if 'admin' is a super user
+Adding 'admin' to the Superuser role
+Generating authentication token
+
+Your authentication URL is valid for 60 seconds.
+http://localhost/auth/login/admin/9G3sb8hjMvrbIJrIf10KKtIj1c8e9mL5
+
+

Copy it and paste it inside your browser, and you will be authenticated as the built-in admin account.

+
+

Hint

+

You can define a standard user account as an administrator from the user card. +To do so, go into Settings > Users, search the user which need to be upgraded and clic on the edit button. +On the displaying card, check Administrator and confirm change using edit button.

+
+
+

Warning

+

If you have not configured the APP_URL setting in the .env file, then the admin url will be generated for localhost. +This is most likely incorrect and you can simply replace localhost with your server IP address or domain name.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/authorizations/index.html b/admin_guides/authorizations/index.html new file mode 100644 index 00000000..7162243f --- /dev/null +++ b/admin_guides/authorizations/index.html @@ -0,0 +1,1536 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Authorizations - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Role-Based Access Control

+

Introduction

+

SeAT supports configuring user access control by means of Role-based Access Control (RBAC). +This allows for SeAT administrators to granularly control who has access to what based on which roles a SeAT user has.

+

In SeAT, the default rule is to deny access. As a result, someone without a permission will not be able to access the requested resource.

+
+

Tip

+

Use roles to define permission without wondering about automation. You will be able to set up role auto assignment with Squads. +The more granular are your roles, the easier they will be to maintain them and built your automation rules.

+
+

Definitions

+

This section aims to clear up the definitions used in the SeAT RBAC implementation.

+
    +
  • +

    User
    +A SeAT user account. This can be either a user account that was created in SeAT itself, or an automatically created account based on SSO. +The only difference between the accounts is that with an SSO account, SeAT has no idea what the account's password is. +Otherwise, everything else is exactly the same.

    +
    • +
  • +

    Scope
    +A scope is a domain grouping different permissions related to the same topic. Permissions from certain scope can be limited (ie: character or corporation).

    +
    • +
  • +

    Permission
    +A Permission is an attribute that is assigned to a Role. It grants access based on the specific permission.

    +
    • +
  • +

    Role
    +A Role is simply a collection of permissions. Users get assigned a roles and inherit the permissions granted by that role. +A user cannot be given a raw permission. Permissions can only be granted by creating a Role, assigning permissions to the Role and granting the role to a user.

    +
    • +
  • +

    Filters
    +Permissions from certain scope can received filters. That simply mean the granted permission is limited to certain conditions. +As an example, you may want to limit the asset permission from character scope to only a selection of character.

    +
    • +
  • +

    Entity
    +An entity is something on which the permission will be applied. It can be a Character, a Corporation or anything else.

    +
    • +
+

Interface

+

To manage roles, you must go into Settings from SeAT sidebar, then choose Access Management.

+
+

Info

+

To be able to manage SeAT roles, you must be authenticated as an administrator user. +Administrators can be managed in the users list, located in Settings.

+
+

Role card

+

The Role card is compounds of two main area.

+

Role Card

+

Left pane contains basic information. It allows you to provide a name, a description and upload an optional logo. +Those information can be sync with any third party platform using the API.

+
+

Tip

+

Provided logo are stored into database - so you don't need to worry when moving your installation.

+
+

Right pane contains role settings. The pane is split in two tabs - first tab is showing the role permissions definitions. +Second pane, the members one, gives you the current role members and related management actions.

+

Role definition

+

Role permissions

+

Role Permissions

+

The role permissions tab is built using a navigation bar, which is showing all available scopes - and the list of permissions from active scope. +Use the scope navigation to show permissions related to each scope.

+

Each permission block is structured as follow:

+
    +
  • a checkbox: if you check it, you mark the permission to be granted by the role
    • +
  • an optional icon: it is visual only and help to pair some permission inside a same scope. It might be useful for large scope like character or corporation to distinguish permission kind. Options include military, financial and industrial.
    • +
  • a user friendly name
    • +
  • an optional description: this is mostly a text explaining the permission purpose
    • +
  • an optional limits button: it will help you to filter/restrict the permission to only a certain population. Only character and corporation scope permissions can be filtered.
    • +
+
+

Warning

+

In SeAT 3, leaving the affiliations of a role empty, meant that the role would apply to no relevant entities. It had no effect. This has changed in SeAT 4. If you give a role a permission with no filter, this permission will apply globally to all entities. For example giving the Corporation Sheet permission to a role with no filter means that the members of the role will be able to see the corporation sheets of every corporation on the server.

+
+

Role members

+

Role Members

+

The role members tab is a table listing all users who are currently assigned the role. All of them receive the benefits of the permissions which have been defined in the permissions tab from that same role. +You will be able to add or remove any user to or from the role using action buttons.

+

To remove an user from the role to which is part, simply click on the "Remove" button located on the member line.

+

To add one or multiple user to the role, use the green "Add" button located at bottom right corner. This will show you a dialog box. Use the drop-down control to find users which you want to add. +Once all users to be add have been chosen, click on the "Close" button located at bottom right corner from that modal. Selected users will be shown with a warning background to highlight their addition to the role. +This means their selection isn't saved yet - you have to apply change using the green "Submit" button located under the General pane.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/buckets/index.html b/admin_guides/buckets/index.html new file mode 100644 index 00000000..79727af6 --- /dev/null +++ b/admin_guides/buckets/index.html @@ -0,0 +1,1431 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Buckets - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Buckets and continuous update

+

Starting with eveseat/console@4.7.0 and eveseat/eveapi@4.8.0, a new system has been designed to ensure continuous updates and reduce load on both SeAT stack and ESI.

+

General

+

Each instance is allowed to get up to 30 buckets. Every bucket will handle a batch of tokens, and their related characters and corporations data update. +Size of bucket is dynamically set based on the following criteria :

+
    +
  • a token can be updated only once every 3600 seconds
    • +
  • a token can be updated in an average of 120 seconds
    • +
+
+

Info

+

Most data ESI endpoint and data they deliver are restricted to a 1-hour cache long. +However, certain are shorter and benefit of dedicated command to allow you update more frequently - please, do not abuse of them.

+
    +
  • esi:update:contracts
    • +
  • esi:update:killmails
    • +
  • esi:update:affiliations
    • +
  • esi:update:notifications
    • +
+
+

Health

+

You can determine a bucket status using seat:buckets:list and seat:buckets:info ID commands. +The first one will show you all existing buckets in the system together with the amount of token they're managing and their status. +The second will show you details about a specific bucket including characters they have the charge of.

+

A bucket can have one of the following status :

+
    +
  • available : there are free slots according to current threshold
    • +
  • balanced : maximum tokens has been reached according to the current threshold, and the bucket cannot handle more token
    • +
  • overload : there are too many tokens handled by this bucket according to the current threshold
    • +
+

Balancing

+

Bucket balancing is run every time a token is created or removed from the system. +As a result, you may find bucket with a certain amount of token at one time and a completely different one at another.

+

If you find yourself with unbalanced buckets, you can force them to be balanced using seat:buckets:balance. +However, depending on instance state, certain buckets will not be able to be more balanced for a time (ie: lack of tokens).

+

Update

+

This system has been designed to ensure there is a bucket to update every two minutes (except for instances with less than 30 tokens). +You can force bucket to be processed and bypass the scheduler using seat:buckets:update - however, keep in mind that tokens handled by updating bucket will be frozen for the next 60 minutes.

+
+

Hint

+

Manual command to force update character and corporation are still available. They require the ID of a tied character.

+
    +
  • esi:update:characters character_id
    • +
  • esi:update:corporations character_id
    • +
+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/docker_admin/index.html b/admin_guides/docker_admin/index.html new file mode 100644 index 00000000..051ce1f1 --- /dev/null +++ b/admin_guides/docker_admin/index.html @@ -0,0 +1,1634 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Docker Admin - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Docker Administration

+

Occasionally you will need to perform administrative tasks in your SeAT instance running within docker. Be it because you would like to configure TLS for the web interface, change the port of the SeAT webserver or simply generate an admin login URL, this guide aims to help you get familiar for the commands needed for this.

+

Many of the commands are exactly the same as those used in a bare metal installation, except for the fact that they are always prefixed with docker compose and run from the same directory that you have the seat docker-compose.yml file stored. If your docker-compose.yml lives in /opt/seat-docker, you will need to cd to that directory first and then execute the docker compose commands.

+
+

Info

+
+

With SeAT 5, we migrated from the docker-compose command to docker compose. Besides the name, they are fully compatible. If you are still on SeAT 4, you have to use docker-compose instead of docker compose for all actions. This applies to all actions, not just the ones listed on this page.

+

Container Status

+

For a quick, birds-eye view on the status of the containers within the SeAT docker stack, the following command may be run:

+
+
+
+
docker-compose ps
+
+
+
+
docker compose ps
+
+
+
+
+

This should give you the name, entry point, current status and internal ports used within the docker network as output.

+

Configuration Changes

+

A dockerized installation of SeAT is primarily configured via a configuration file located at .env. Configuration options such as your applications SSO secrets, SeAT's web server ports are amongst the many configuration options available in this file.

+

Making changes to this file requires the docker stack to be restarted so that the configuration may be applies. An example case would be when you configure SSO for your instance.

+

Once you have made a configuration change, save the .env file and restart the stack by simply running the following command from the path where the docker-compose.yml lives:

+
+
+
+
docker-compose up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+

Live Container Logs

+

Getting an idea of what is happening inside of the containers may be useful for many things, including debugging any issues that may occur. All of the containers generate logs that can be viewed either in isolation, or all of the containers in the stack.

+
+
+
+

To view a single services' logs (seat-web in this examples case), run:

+
docker-compose logs --tail 10 -f seat-web
+
+

All services can referenced by their name using docker compose. You can see the service names here. At the time of writing this doc, the available services were: mariadb, redis, traefik, seat-web, seat-worker and seat-cron.

+
+
+

To view a single services' logs (front in this examples case), run:

+
docker compose logs --tail 10 -f front
+
+

All services can referenced by their name using docker compose. You can see the service names here and in the adjacent docker-compose.x.yml files. At the time of writing this doc, the available services were: mariadb, cache, traefik, front, worker and scheduler.

+
+
+
+

To view all service logs at once, run:

+
+
+
+
docker-compose logs --tail 10 -f
+
+
+
+
docker compose logs --tail 10 -f
+
+
+
+
+

Once you are done viewing the output, simply pressing ^C will exit the log viewer.

+

Application Logs

+

While most processes will output information to stdout (which is what you will see when you run docker-compose logs), there are some app specific logs also generated.

+

Logs - Web UI

+
+
+
+

If you are getting HTTP 500's, or other exception when using the web interface, the best place to find the relevant logs will be in the seat-web service, in the /var/www/seat/storage/logs directory. To reach them, run docker-compose exec seat-web bash. This will drop you into bash shell in the container:

+
1
+2
$ docker-compose exec seat-web bash
+root@9aff5b002ca0:/var/www/seat#
+
+
+
+

If you are getting HTTP 500's, or other exception when using the web interface, the best place to find the relevant logs will be in the front service, in the /var/www/seat/storage/logs directory. To reach them, run docker-compose exec front bash. This will drop you into bash shell in the container:

+
1
+2
$ docker-compose exec front bash
+root@9aff5b002ca0:/var/www/seat#
+
+
+
+
+

Next, cd to the logs directory with:

+
cd storage/logs/
+
+

This directory should have daily log files for you to view.

+

Logs - Worker / Updaters

+
+
+
+

If you think your workers may be causing some exceptions, or you want to investigate why they may be failing, you can do so in the seat-worker service. Just like for the web UI, get a bash shell and cd to the logs directory.

+
1
+2
+3
+4
# docker-compose exec seat-worker bash
+root@8ed8967348f1:/var/www/seat# cd storage/logs/
+root@8ed8967348f1:/var/www/seat/storage/logs# ls
+eseye-2020-08-23.log
+
+
+
+

If you think your workers may be causing some exceptions, or you want to investigate why they may be failing, you can do so in the worker service. Just like for the web UI, get a bash shell and cd to the logs directory.

+
1
+2
+3
+4
# docker compose exec worker bash
+root@8ed8967348f1:/var/www/seat# cd storage/logs/
+root@8ed8967348f1:/var/www/seat/storage/logs# ls
+eseye-2020-08-23.log
+
+
+
+
+

The eseye log as well as Laravel log should help you debug what is going on.

+

Installing Plugins

+

SeAT provides the ability for third party developers to integrate with the core environment to extend its features and functionality. It is possible to install those plugins in a docker environment. Installing a plugin is relatively easy too. All you need to do is add the plugin name to your SEAT_PLUGINS variable in the .env file and run docker-compose up -d again. The plugin will be read from the .env file and installed as the application container starts.

+

For example. Open the .env file (which is most probably at /opt/seat-docker/.env) and edit the SEAT_PLUGINS variable to include the package you want to install. In our example we use the pseudo package called user/seat-plugin:

+
1
+2
+3
+4
+5
# SeAT Plugins
+# This is a list of the all of the third party plugins that you
+# would like to install as part of SeAT. Package names should be
+# comma separated if multiple packages should be installed.
+SEAT_PLUGINS=user/seat-plugin
+
+

Save your .env file and run docker-compose up -d to restart the stack with the new plugins as part of it. Depending on how big the plugin itself may be, this could take a few moments to complete.

+

You can monitor the installation process by running:

+
+
+
+
docker-compose logs --tail 10 -f
+
+
+
+
docker compose logs --tail 10 -f
+
+
+
+
+

Database Backups and Restore

+

Backups. They are important and really simple to do. To perform a backup of the current database used within the docker stack, compressing and saving it to a file called seat_backup.sql.gz, run:

+
+
+
+
docker-compose exec mariadb sh -c 'exec mysqldump "$MYSQL_DATABASE" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"' | gzip > seat_backup.sql.gz
+
+
+
+
docker compose exec mariadb sh -c 'exec mysqldump "$MYSQL_DATABASE" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"' | gzip > seat_backup.sql.gz
+
+
+
+
+

To restore a backup to a new dockerized instance of SeAT, run:

+
+
+
+
zcat seat_backup.sql.gz | docker-compose exec -T mariadb sh -c 'exec mysql "$MYSQL_DATABASE" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"'
+
+
+
+
zcat seat_backup.sql.gz | docker compose exec -T mariadb sh -c 'exec mysql "$MYSQL_DATABASE" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"'
+
+
+
+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/scaled_deployments/index.html b/admin_guides/scaled_deployments/index.html new file mode 100644 index 00000000..b1d5b9c5 --- /dev/null +++ b/admin_guides/scaled_deployments/index.html @@ -0,0 +1,1589 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Scaled Deployments - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+
+

DEPRECATED!!!

+

This guide is deprecated and is not functional in SeAT v3. If you need more performance in SeAT v3 then you have two options, move the DB alone to another server, and/or beef up the server SeAT is running on. This guide may be updated in the future when horizontal scaling is viable again. It is left as is for now due to academic and nostalgic reasons.

+
+

Scaled SeAT Deployments

+

At some stage, you may come to a point where a single install of SeAT might not be enough to process api key updates. +Thankfully, it is actually very easy to scale SeAT horizontally in order to improve performance. +This document aims to share some need to knows before embarking on a tiered installation of SeAT.

+

Definitions

+

Lets get some definitions cleared up.

+

Server

+

A server is defined as any VPS, hardware, docker container, or other form of virtualization. +When talking performance though, keep in mind that there will probably be very little performance gains when everything runs on the same physical hardware instance.

+

SeAT component

+

A SeAT Component is a collection of SeAT packages and configurations that is responsible for performing a specific task. +Tasks include the SeAT Web Interface, the job workers or dispatchers.

+

Components

+

Before we can talk scale, we need to understand which components SeAT actually consists of. +We will not talk about the immutable resources here as they will be mentioned in the next section.

+

So, which components are there to SeAT?

+
    +
  • The web front end.
    • +
  • The queue workers.
    • +
  • The job dispatcher.
    • +
+

Each of these components can live on their own server and must share the same immutable resources.

+

Immutable resources

+

While almost every component in SeAT can 'run on its own', there are some services that SeAT consumes that SeAT can not scale itself. +Instead, SeAT can consume a clustered or load balanced instance of these services. +There are various reasons for this where the most important is that state is maintained between queue workers using Redis and MariaDB.

+

Services that should be shared between all SeAT components are:

+
    +
  • The Redis cache.
    • +
  • The MariaDB database.
    • +
+

When mentioning these components, they can definitely exist in their clustered/load balanced forms. +For Redis, have a look at their Redis cluster tutorial and for MariaDB, +you can have a look at their MariaDB cluster installation.

+

Simple scaled setup

+

The following example setup is probably the most simple option to gain performance improvements by scaling out. +The gist of it is that we simply add more queue worker components to the SeAT setup.

+

Lets start by taking a look at a diagram, showing the extra queue worker component added.

+

simple scale

+

Installing a new server with only the queue worker component setup can bring a significant speed boost into the environment. +A new queue worker could be configured to run an extra 4-6 jobs. This queue worker must be configured to make use of the immutable resources.

+

More complicated scaled setup

+

Of course, one can totally go full nelson and explode all of the components in use. +Below is an example deployment (with data flow links, red for redis, blue for MariaDB) that shows how each SeAT component can live on its own server.

+

complex scale

+

Component setups

+

Lets talk about component configurations quickly. +Apart from the immutable resources, all of the software needed can be sourced from SeAT packages. +All of the standard requirements such as PHP7.1 and Supervisor 3 also apply. However, not all components would need a web server for example.

+

Below are the descriptions (and short requirements list) for the different SeAT components.

+

Web front end

+

To setup a web front end component, use the following steps:

+
    +
  • Ensure you have at least PHP7.1 installed.
    • +
  • Ensure that you have a web server installed that can serve the public/ directory from the SeAT project.
    • +
  • Ensure that you have composer installed and available in PATH.
    • +
  • Download SeAT somewhere like /var/www/seat using composer create-project eveseat/seat /var/www/seat --no-dev.
    • +
  • Once installed, configure the .env files database and Redis settings to connect to your immutable sources.
    • +
+

Queue worker

+

To setup a queue worker component, use the following steps:

+
    +
  • Ensure you have at least PHP7.1 installed.
    • +
  • Ensure that you have supervisor3 installed.
    • +
  • Ensure that you have composer installed and available in PATH.
    • +
  • Download SeAT somewhere using composer create-project eveseat/seat --no-dev.
    • +
  • Once installed, configure the .env files database and Redis settings to connect to your immutable sources.
    • +
  • Configure the workers in a seat.ini file for supervisor to start.
    • +
+

Job dispatcher

+

To setup a job dispatcher component, use the following steps:

+
    +
  • Ensure you have at least PHP7.1 installed.
    • +
  • Ensure that you have composer installed and available in PATH.
    • +
  • Download SeAT somewhere like /var/www/seat using composer create-project eveseat/seat /var/www/seat --no-dev.
    • +
  • Once installed, configure the .env files database and Redis settings to connect to your immutable sources.
    • +
  • Setup the cronjob to run php artisan schedule:run 1>> /dev/null 2>&1 every minute.
    • +
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/squads/index.html b/admin_guides/squads/index.html new file mode 100644 index 00000000..2b9759a9 --- /dev/null +++ b/admin_guides/squads/index.html @@ -0,0 +1,1649 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Squads - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Squads

+

Introduction

+

Since SeAT 4.0, there is a way to apply automatic logic between an end user and its roles. +The purpose is to keep distinct the security and automations.

+

Squads is the core implementation of the deprecated seat-groups plugin.

+

Squads Types

+

There are multiple kinds of squad. The way they work and the automations they apply depend on their type.

+

Automatic

+

This is the simplest squad type. +Membership of a squad of this type is controlled by the filters (see below) set for the squad.

+

A member of an automatic squad cannot remove themselves from the group. +If a user no longer fulfils the criteria of the filter set for the squad they will be automatically removed from it.

+

Manual

+

Manual squads have to be applied to, the processing of the application depends on whether there is a moderator for the group or not.

+

If there is no moderator the application will be automatically accepted.

+

If there is at least one moderator they can accept or reject applications.

+

Filters applied to a squad of this type will have two effects: +- hide the "Apply" button if the filter criteria are not met +- kick the member from the group if the filter criteria are not met

+

Hidden

+

Hidden squads are visible exclusively to their members and admins. +To be part of a hidden squad, the user needs to be added to it by an admin.

+

This mean, only admin user can invite another user to a hidden squad.

+

Squads Filters

+

Filters have different behaviors depending on the Squad Type. +In case the Squad is of auto type, filters will be applied continuously to invite and kick members from the Squad - based on user changes.

+

Otherwise, filters are used to automatically kick members from a Squad and determine the availability of the "Apply" button on Squad Card.

+

Squads Filters have been designed to assist you to build rules which will determine whether a given user is eligible for a Squad. +You pair different conditions together and link them with match keywords.

+

Match keywords can be either All or Any. +All mean all conditions must be met by the user for them to be eligible. +Any means that a user is eligible if they meet any of the conditions.

+

To add a condition, use Add Rule button located at the end of the modal. +In case you have to build a complex rule, use Add Group which will allow you to pair multiple conditions in a single rule.

+
+

Info

+

Filters come with multiple operators. Not all operators work with all filters. +Is and Is not are used to indicate either equality with criteria or inequality. Those operators are the most common and work with nearly all filter types. +Contains is used to indicate that criteria must be included in a domain. This operator currently only works with the Scopes filter.

+
+

Squads Filters

+
+

Example

+

In the example above, we want only users who own at least one character (inside either Get Off My Lawn OR Toilet Paper. alliances) AND with skill Capital Ships to be eligible for membership in our Squad.

+
+

Squad Applications

+

Applications are only available to manual squads.

+

For a user to be able to apply to a manual squad they need to meed the squads filter criteria. Otherwise, application button will not be available.

+

If the user applies to a moderated squad, they are required to fill an application form. +This will leave you the ability to build workflow internally and allow moderators to check any incoming members. +Users can also cancel squad applications at any time using the Cancel button which will replace the Join button.

+

Squad Moderators

+

Moderators of a Squad don't need to be part of that squad. +They will be able to see a list of every member of each squad they moderate, allowing them to invite further members or kick existing ones.

+

Squad moderators can also see Squad candidates, the time when they applied and each application form. +From there, they can approve an application or reject it.

+

When an application is approved, the user who sent it is becomes a member of the Squad. +If an application is denied, the application is removed and user can submit a new application.

+

Only administrator users can add or remove moderators to/from a Squad.

+

Interface

+

Squads List

+

Squads list is the entry point of squads. You can create a new squad, search for a squad, show available squads and get squad status from there. +The Squads list is available to all users, without any restriction. You can access it using Squads from the left sidebar.

+

Sidebar

+

The list is split in three main areas. +First area, at top, contains controls which will allow you to create a squad, or filter the shown squads. +The main area, contains squads tiles from the active page. You can get up to six squads per page. +Footer area is the pagination controls - allowing you to switch displayed page (first, previous, current, next and last).

+

Squad List

+

Every Squad Tile is built following the same pattern :

+

1) Logo +2) Name and description +3) User status related to that squad +4) Metadata +5) Type

+

Squad Tile

+

Except metadata, other attributes are self-explained. Metadata is a list of counters showing you, from left to right:

+
    +
  • number of members of the squad (in white)
    • +
  • number of moderators of the squad (in orange)
    • +
  • number of applicants to the squad (in blue)
    • +
+
+

Hint

+

Squad Logo is a visual way for your end user to identify quickly a Squad. +By default, logo are generated based on the Squad Name - but you can customise it in the Squad settings.

+
+

Squads Card

+

When you click on a Squad Tile, you'll land on the related Squad Card. Squad Card is the landing area of a Squad. +You will retrieve summarised information you had on the tile in the general pane.

+

In case the Squad is manual, you will get access to the list of Squad moderators. +This list is public, this mean everyone can see it, without consideration if he's or not a member of that Squad.

+

Squad Card General Pane

+

Under the general pane, you'll get access to the list of roles assigned by the Squad. +This list is disclosed to admin user only. This mean neither "standard user" or moderators will get access to it.

+

From that pane, you are able to remove a role from the squad or add other ones to it.

+

Squad Card Role Pane

+

Members pane is visible to all moderators and squad members. +Moderators can invite or kick user from the squad using actions buttons.

+

Squad Card Members Pane

+
+

Info

+

When an user is kicked or invited from/to a Squad, the event is shown into security logs. +You will be able to see who kick or invite any user from/to any Squad.

+
+

Last but not least, there is an extra Candidates pane which is available on Manual Moderated Squad. +Squad applications can be managed from this area.

+

Squad Card Applications Pane

+

Squads Settings

+

When you create a new Squad, you have to fill a small form which will define it. Mandatory elements are :

+
    +
  • The name of created squad which have to be unique
    • +
  • Squad Type (between Auto, Hidden and Manual - see Squads Types)
    • +
  • A description, which will be displayed on both Squad Card and Squad Tile
    • +
+

You also can upload a shiny logo which will be used instead the generated icon and provide filters for squad eligibility.

+

Squad Creation

+
+

Caution

+

As soon as you save your Squad, filters are applied. +In case the Squad is of auto type, eligible members will be added to it. +For any other Squad Types, non-eligible members will be kicked from the Squad

+
+
+

Hint

+

Don't pay attention to your Squads Description. If it's too long, it will be shortened when displayed on the Squad Tile. +However, the full description will always be available on the Squad Card into the general pane.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/admin_guides/understanding_tracking/index.html b/admin_guides/understanding_tracking/index.html new file mode 100644 index 00000000..157b3028 --- /dev/null +++ b/admin_guides/understanding_tracking/index.html @@ -0,0 +1,1473 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Understanding Tracking - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Understanding Tracking

+

Introduction

+

SeAT implements the Google Analytics Measurement Protocol. +This document aims to explain in as much detail as possible how it has been implemented in SeAT, as well as what is tracked and what is not. +This document aims to be as transparent as possible.

+

Why

+

Well, the most obvious is it being nice to know how much SeAT is actually being used. +One may argue that Github & packagist gives statistics on how many times the project has been installed / cloned, but that does not really +reflect how many actual active installations there are.

+

Knowing how many active installs there are, encourages development.

+

Lastly, certain exception types are also sent as hits. This helps immensely with figuring out if a new version may have a serious bug.

+

How its implemented

+

First of all, the Google Analytics Measurement Protocol is really just that. It just measures usage. In summary, when certain events happen, +only a hit with what happened is sent. No other data is sent with the hit.

+

For example. When the scheduler queues jobs, a hit is sent that says that this happened, and that it happened for x amount of keys. +This can be seen in the following line of code: QueueKeys. +It can also be seen that no other data goes along with the hit. For example, the access_token and refresh_token +(which is what most will be worried about) does not go with the hit.

+

Once a hit is getting ready to be sent, information such as which OS/Version as well as versions of installed SeAT packages gets sent along with the hit. +This can be seen in the following lines of code.

+

How are you protecting my privacy?

+

Very special care has been taken to ensure that no personally identifiable information goes along with the Measurement Protocol hits. +In fact, its actually not allowed and serves no purpose for tracking. +That being said, the following actions have been taken to ensure that privacy is key:

+ + +

Sure!

+ +

Are the stats a secret?

+

Not at all. However, as a start I am going to limit access to people whom have actively contributed towards SeAT. +If you would like access, please ping me on Slack.

+

How do I disable this crap?

+

If you insist on disabling the usage tracking, you can do this (as a SeAT administrator) by browsing to Configuration -> SeAT Settings and +setting Allow Tracking to No.

+

disable tracking

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/assets/images/favicon.png b/assets/images/favicon.png new file mode 100644 index 00000000..1cf13b9f Binary files /dev/null and b/assets/images/favicon.png differ diff --git a/assets/javascripts/bundle.51d95adb.min.js b/assets/javascripts/bundle.51d95adb.min.js new file mode 100644 index 00000000..b20ec683 --- /dev/null +++ b/assets/javascripts/bundle.51d95adb.min.js @@ -0,0 +1,29 @@ +"use strict";(()=>{var Hi=Object.create;var xr=Object.defineProperty;var Pi=Object.getOwnPropertyDescriptor;var $i=Object.getOwnPropertyNames,kt=Object.getOwnPropertySymbols,Ii=Object.getPrototypeOf,Er=Object.prototype.hasOwnProperty,an=Object.prototype.propertyIsEnumerable;var on=(e,t,r)=>t in e?xr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,P=(e,t)=>{for(var r in t||(t={}))Er.call(t,r)&&on(e,r,t[r]);if(kt)for(var r of kt(t))an.call(t,r)&&on(e,r,t[r]);return e};var sn=(e,t)=>{var r={};for(var n in e)Er.call(e,n)&&t.indexOf(n)<0&&(r[n]=e[n]);if(e!=null&&kt)for(var n of kt(e))t.indexOf(n)<0&&an.call(e,n)&&(r[n]=e[n]);return r};var Ht=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Fi=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of $i(t))!Er.call(e,o)&&o!==r&&xr(e,o,{get:()=>t[o],enumerable:!(n=Pi(t,o))||n.enumerable});return e};var yt=(e,t,r)=>(r=e!=null?Hi(Ii(e)):{},Fi(t||!e||!e.__esModule?xr(r,"default",{value:e,enumerable:!0}):r,e));var fn=Ht((wr,cn)=>{(function(e,t){typeof wr=="object"&&typeof cn!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(wr,function(){"use strict";function e(r){var n=!0,o=!1,i=null,a={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function s(T){return!!(T&&T!==document&&T.nodeName!=="HTML"&&T.nodeName!=="BODY"&&"classList"in T&&"contains"in T.classList)}function f(T){var Ke=T.type,We=T.tagName;return!!(We==="INPUT"&&a[Ke]&&!T.readOnly||We==="TEXTAREA"&&!T.readOnly||T.isContentEditable)}function c(T){T.classList.contains("focus-visible")||(T.classList.add("focus-visible"),T.setAttribute("data-focus-visible-added",""))}function u(T){T.hasAttribute("data-focus-visible-added")&&(T.classList.remove("focus-visible"),T.removeAttribute("data-focus-visible-added"))}function p(T){T.metaKey||T.altKey||T.ctrlKey||(s(r.activeElement)&&c(r.activeElement),n=!0)}function m(T){n=!1}function d(T){s(T.target)&&(n||f(T.target))&&c(T.target)}function h(T){s(T.target)&&(T.target.classList.contains("focus-visible")||T.target.hasAttribute("data-focus-visible-added"))&&(o=!0,window.clearTimeout(i),i=window.setTimeout(function(){o=!1},100),u(T.target))}function v(T){document.visibilityState==="hidden"&&(o&&(n=!0),B())}function B(){document.addEventListener("mousemove",z),document.addEventListener("mousedown",z),document.addEventListener("mouseup",z),document.addEventListener("pointermove",z),document.addEventListener("pointerdown",z),document.addEventListener("pointerup",z),document.addEventListener("touchmove",z),document.addEventListener("touchstart",z),document.addEventListener("touchend",z)}function re(){document.removeEventListener("mousemove",z),document.removeEventListener("mousedown",z),document.removeEventListener("mouseup",z),document.removeEventListener("pointermove",z),document.removeEventListener("pointerdown",z),document.removeEventListener("pointerup",z),document.removeEventListener("touchmove",z),document.removeEventListener("touchstart",z),document.removeEventListener("touchend",z)}function z(T){T.target.nodeName&&T.target.nodeName.toLowerCase()==="html"||(n=!1,re())}document.addEventListener("keydown",p,!0),document.addEventListener("mousedown",m,!0),document.addEventListener("pointerdown",m,!0),document.addEventListener("touchstart",m,!0),document.addEventListener("visibilitychange",v,!0),B(),r.addEventListener("focus",d,!0),r.addEventListener("blur",h,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var un=Ht(Sr=>{(function(e){var t=function(){try{return!!Symbol.iterator}catch(c){return!1}},r=t(),n=function(c){var u={next:function(){var p=c.shift();return{done:p===void 0,value:p}}};return r&&(u[Symbol.iterator]=function(){return u}),u},o=function(c){return encodeURIComponent(c).replace(/%20/g,"+")},i=function(c){return decodeURIComponent(String(c).replace(/\+/g," "))},a=function(){var c=function(p){Object.defineProperty(this,"_entries",{writable:!0,value:{}});var m=typeof p;if(m!=="undefined")if(m==="string")p!==""&&this._fromString(p);else if(p instanceof c){var d=this;p.forEach(function(re,z){d.append(z,re)})}else if(p!==null&&m==="object")if(Object.prototype.toString.call(p)==="[object Array]")for(var h=0;hd[0]?1:0}),c._entries&&(c._entries={});for(var p=0;p1?i(d[1]):"")}})})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Sr);(function(e){var t=function(){try{var o=new e.URL("b","http://a");return o.pathname="c d",o.href==="http://a/c%20d"&&o.searchParams}catch(i){return!1}},r=function(){var o=e.URL,i=function(f,c){typeof f!="string"&&(f=String(f)),c&&typeof c!="string"&&(c=String(c));var u=document,p;if(c&&(e.location===void 0||c!==e.location.href)){c=c.toLowerCase(),u=document.implementation.createHTMLDocument(""),p=u.createElement("base"),p.href=c,u.head.appendChild(p);try{if(p.href.indexOf(c)!==0)throw new Error(p.href)}catch(T){throw new Error("URL unable to set base "+c+" due to "+T)}}var m=u.createElement("a");m.href=f,p&&(u.body.appendChild(m),m.href=m.href);var d=u.createElement("input");if(d.type="url",d.value=f,m.protocol===":"||!/:/.test(m.href)||!d.checkValidity()&&!c)throw new TypeError("Invalid URL");Object.defineProperty(this,"_anchorElement",{value:m});var h=new e.URLSearchParams(this.search),v=!0,B=!0,re=this;["append","delete","set"].forEach(function(T){var Ke=h[T];h[T]=function(){Ke.apply(h,arguments),v&&(B=!1,re.search=h.toString(),B=!0)}}),Object.defineProperty(this,"searchParams",{value:h,enumerable:!0});var z=void 0;Object.defineProperty(this,"_updateSearchParams",{enumerable:!1,configurable:!1,writable:!1,value:function(){this.search!==z&&(z=this.search,B&&(v=!1,this.searchParams._fromString(this.search),v=!0))}})},a=i.prototype,s=function(f){Object.defineProperty(a,f,{get:function(){return this._anchorElement[f]},set:function(c){this._anchorElement[f]=c},enumerable:!0})};["hash","host","hostname","port","protocol"].forEach(function(f){s(f)}),Object.defineProperty(a,"search",{get:function(){return this._anchorElement.search},set:function(f){this._anchorElement.search=f,this._updateSearchParams()},enumerable:!0}),Object.defineProperties(a,{toString:{get:function(){var f=this;return function(){return f.href}}},href:{get:function(){return this._anchorElement.href.replace(/\?$/,"")},set:function(f){this._anchorElement.href=f,this._updateSearchParams()},enumerable:!0},pathname:{get:function(){return this._anchorElement.pathname.replace(/(^\/?)/,"/")},set:function(f){this._anchorElement.pathname=f},enumerable:!0},origin:{get:function(){var f={"http:":80,"https:":443,"ftp:":21}[this._anchorElement.protocol],c=this._anchorElement.port!=f&&this._anchorElement.port!=="";return this._anchorElement.protocol+"//"+this._anchorElement.hostname+(c?":"+this._anchorElement.port:"")},enumerable:!0},password:{get:function(){return""},set:function(f){},enumerable:!0},username:{get:function(){return""},set:function(f){},enumerable:!0}}),i.createObjectURL=function(f){return o.createObjectURL.apply(o,arguments)},i.revokeObjectURL=function(f){return o.revokeObjectURL.apply(o,arguments)},e.URL=i};if(t()||r(),e.location!==void 0&&!("origin"in e.location)){var n=function(){return e.location.protocol+"//"+e.location.hostname+(e.location.port?":"+e.location.port:"")};try{Object.defineProperty(e.location,"origin",{get:n,enumerable:!0})}catch(o){setInterval(function(){e.location.origin=n()},100)}}})(typeof global!="undefined"?global:typeof window!="undefined"?window:typeof self!="undefined"?self:Sr)});var Qr=Ht((Lt,Kr)=>{/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */(function(t,r){typeof Lt=="object"&&typeof Kr=="object"?Kr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Lt=="object"?Lt.ClipboardJS=r():t.ClipboardJS=r()})(Lt,function(){return function(){var e={686:function(n,o,i){"use strict";i.d(o,{default:function(){return ki}});var a=i(279),s=i.n(a),f=i(370),c=i.n(f),u=i(817),p=i.n(u);function m(j){try{return document.execCommand(j)}catch(O){return!1}}var d=function(O){var w=p()(O);return m("cut"),w},h=d;function v(j){var O=document.documentElement.getAttribute("dir")==="rtl",w=document.createElement("textarea");w.style.fontSize="12pt",w.style.border="0",w.style.padding="0",w.style.margin="0",w.style.position="absolute",w.style[O?"right":"left"]="-9999px";var k=window.pageYOffset||document.documentElement.scrollTop;return w.style.top="".concat(k,"px"),w.setAttribute("readonly",""),w.value=j,w}var B=function(O,w){var k=v(O);w.container.appendChild(k);var F=p()(k);return m("copy"),k.remove(),F},re=function(O){var w=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},k="";return typeof O=="string"?k=B(O,w):O instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(O==null?void 0:O.type)?k=B(O.value,w):(k=p()(O),m("copy")),k},z=re;function T(j){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?T=function(w){return typeof w}:T=function(w){return w&&typeof Symbol=="function"&&w.constructor===Symbol&&w!==Symbol.prototype?"symbol":typeof w},T(j)}var Ke=function(){var O=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},w=O.action,k=w===void 0?"copy":w,F=O.container,q=O.target,Le=O.text;if(k!=="copy"&&k!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(q!==void 0)if(q&&T(q)==="object"&&q.nodeType===1){if(k==="copy"&&q.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(k==="cut"&&(q.hasAttribute("readonly")||q.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(Le)return z(Le,{container:F});if(q)return k==="cut"?h(q):z(q,{container:F})},We=Ke;function Ie(j){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?Ie=function(w){return typeof w}:Ie=function(w){return w&&typeof Symbol=="function"&&w.constructor===Symbol&&w!==Symbol.prototype?"symbol":typeof w},Ie(j)}function Ti(j,O){if(!(j instanceof O))throw new TypeError("Cannot call a class as a function")}function nn(j,O){for(var w=0;w0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof F.action=="function"?F.action:this.defaultAction,this.target=typeof F.target=="function"?F.target:this.defaultTarget,this.text=typeof F.text=="function"?F.text:this.defaultText,this.container=Ie(F.container)==="object"?F.container:document.body}},{key:"listenClick",value:function(F){var q=this;this.listener=c()(F,"click",function(Le){return q.onClick(Le)})}},{key:"onClick",value:function(F){var q=F.delegateTarget||F.currentTarget,Le=this.action(q)||"copy",Rt=We({action:Le,container:this.container,target:this.target(q),text:this.text(q)});this.emit(Rt?"success":"error",{action:Le,text:Rt,trigger:q,clearSelection:function(){q&&q.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(F){return yr("action",F)}},{key:"defaultTarget",value:function(F){var q=yr("target",F);if(q)return document.querySelector(q)}},{key:"defaultText",value:function(F){return yr("text",F)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(F){var q=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return z(F,q)}},{key:"cut",value:function(F){return h(F)}},{key:"isSupported",value:function(){var F=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],q=typeof F=="string"?[F]:F,Le=!!document.queryCommandSupported;return q.forEach(function(Rt){Le=Le&&!!document.queryCommandSupported(Rt)}),Le}}]),w}(s()),ki=Ri},828:function(n){var o=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function a(s,f){for(;s&&s.nodeType!==o;){if(typeof s.matches=="function"&&s.matches(f))return s;s=s.parentNode}}n.exports=a},438:function(n,o,i){var a=i(828);function s(u,p,m,d,h){var v=c.apply(this,arguments);return u.addEventListener(m,v,h),{destroy:function(){u.removeEventListener(m,v,h)}}}function f(u,p,m,d,h){return typeof u.addEventListener=="function"?s.apply(null,arguments):typeof m=="function"?s.bind(null,document).apply(null,arguments):(typeof u=="string"&&(u=document.querySelectorAll(u)),Array.prototype.map.call(u,function(v){return s(v,p,m,d,h)}))}function c(u,p,m,d){return function(h){h.delegateTarget=a(h.target,p),h.delegateTarget&&d.call(u,h)}}n.exports=f},879:function(n,o){o.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},o.nodeList=function(i){var a=Object.prototype.toString.call(i);return i!==void 0&&(a==="[object NodeList]"||a==="[object HTMLCollection]")&&"length"in i&&(i.length===0||o.node(i[0]))},o.string=function(i){return typeof i=="string"||i instanceof String},o.fn=function(i){var a=Object.prototype.toString.call(i);return a==="[object Function]"}},370:function(n,o,i){var a=i(879),s=i(438);function f(m,d,h){if(!m&&!d&&!h)throw new Error("Missing required arguments");if(!a.string(d))throw new TypeError("Second argument must be a String");if(!a.fn(h))throw new TypeError("Third argument must be a Function");if(a.node(m))return c(m,d,h);if(a.nodeList(m))return u(m,d,h);if(a.string(m))return p(m,d,h);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function c(m,d,h){return m.addEventListener(d,h),{destroy:function(){m.removeEventListener(d,h)}}}function u(m,d,h){return Array.prototype.forEach.call(m,function(v){v.addEventListener(d,h)}),{destroy:function(){Array.prototype.forEach.call(m,function(v){v.removeEventListener(d,h)})}}}function p(m,d,h){return s(document.body,m,d,h)}n.exports=f},817:function(n){function o(i){var a;if(i.nodeName==="SELECT")i.focus(),a=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var s=i.hasAttribute("readonly");s||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),s||i.removeAttribute("readonly"),a=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var f=window.getSelection(),c=document.createRange();c.selectNodeContents(i),f.removeAllRanges(),f.addRange(c),a=f.toString()}return a}n.exports=o},279:function(n){function o(){}o.prototype={on:function(i,a,s){var f=this.e||(this.e={});return(f[i]||(f[i]=[])).push({fn:a,ctx:s}),this},once:function(i,a,s){var f=this;function c(){f.off(i,c),a.apply(s,arguments)}return c._=a,this.on(i,c,s)},emit:function(i){var a=[].slice.call(arguments,1),s=((this.e||(this.e={}))[i]||[]).slice(),f=0,c=s.length;for(f;f{"use strict";/*! + * escape-html + * Copyright(c) 2012-2013 TJ Holowaychuk + * Copyright(c) 2015 Andreas Lubbe + * Copyright(c) 2015 Tiancheng "Timothy" Gu + * MIT Licensed + */var is=/["'&<>]/;Jo.exports=as;function as(e){var t=""+e,r=is.exec(t);if(!r)return t;var n,o="",i=0,a=0;for(i=r.index;i0&&i[i.length-1])&&(c[0]===6||c[0]===2)){r=0;continue}if(c[0]===3&&(!i||c[1]>i[0]&&c[1]=e.length&&(e=void 0),{value:e&&e[n++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function W(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var n=r.call(e),o,i=[],a;try{for(;(t===void 0||t-- >0)&&!(o=n.next()).done;)i.push(o.value)}catch(s){a={error:s}}finally{try{o&&!o.done&&(r=n.return)&&r.call(n)}finally{if(a)throw a.error}}return i}function D(e,t,r){if(r||arguments.length===2)for(var n=0,o=t.length,i;n1||s(m,d)})})}function s(m,d){try{f(n[m](d))}catch(h){p(i[0][3],h)}}function f(m){m.value instanceof Xe?Promise.resolve(m.value.v).then(c,u):p(i[0][2],m)}function c(m){s("next",m)}function u(m){s("throw",m)}function p(m,d){m(d),i.shift(),i.length&&s(i[0][0],i[0][1])}}function mn(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof xe=="function"?xe(e):e[Symbol.iterator](),r={},n("next"),n("throw"),n("return"),r[Symbol.asyncIterator]=function(){return this},r);function n(i){r[i]=e[i]&&function(a){return new Promise(function(s,f){a=e[i](a),o(s,f,a.done,a.value)})}}function o(i,a,s,f){Promise.resolve(f).then(function(c){i({value:c,done:s})},a)}}function A(e){return typeof e=="function"}function at(e){var t=function(n){Error.call(n),n.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var $t=at(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: +`+r.map(function(n,o){return o+1+") "+n.toString()}).join(` + `):"",this.name="UnsubscriptionError",this.errors=r}});function De(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Fe=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,n,o,i;if(!this.closed){this.closed=!0;var a=this._parentage;if(a)if(this._parentage=null,Array.isArray(a))try{for(var s=xe(a),f=s.next();!f.done;f=s.next()){var c=f.value;c.remove(this)}}catch(v){t={error:v}}finally{try{f&&!f.done&&(r=s.return)&&r.call(s)}finally{if(t)throw t.error}}else a.remove(this);var u=this.initialTeardown;if(A(u))try{u()}catch(v){i=v instanceof $t?v.errors:[v]}var p=this._finalizers;if(p){this._finalizers=null;try{for(var m=xe(p),d=m.next();!d.done;d=m.next()){var h=d.value;try{dn(h)}catch(v){i=i!=null?i:[],v instanceof $t?i=D(D([],W(i)),W(v.errors)):i.push(v)}}}catch(v){n={error:v}}finally{try{d&&!d.done&&(o=m.return)&&o.call(m)}finally{if(n)throw n.error}}}if(i)throw new $t(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)dn(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&De(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&De(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Or=Fe.EMPTY;function It(e){return e instanceof Fe||e&&"closed"in e&&A(e.remove)&&A(e.add)&&A(e.unsubscribe)}function dn(e){A(e)?e():e.unsubscribe()}var Ae={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var st={setTimeout:function(e,t){for(var r=[],n=2;n0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var n=this,o=this,i=o.hasError,a=o.isStopped,s=o.observers;return i||a?Or:(this.currentObservers=null,s.push(r),new Fe(function(){n.currentObservers=null,De(s,r)}))},t.prototype._checkFinalizedStatuses=function(r){var n=this,o=n.hasError,i=n.thrownError,a=n.isStopped;o?r.error(i):a&&r.complete()},t.prototype.asObservable=function(){var r=new U;return r.source=this,r},t.create=function(r,n){return new wn(r,n)},t}(U);var wn=function(e){ne(t,e);function t(r,n){var o=e.call(this)||this;return o.destination=r,o.source=n,o}return t.prototype.next=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.next)===null||o===void 0||o.call(n,r)},t.prototype.error=function(r){var n,o;(o=(n=this.destination)===null||n===void 0?void 0:n.error)===null||o===void 0||o.call(n,r)},t.prototype.complete=function(){var r,n;(n=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||n===void 0||n.call(r)},t.prototype._subscribe=function(r){var n,o;return(o=(n=this.source)===null||n===void 0?void 0:n.subscribe(r))!==null&&o!==void 0?o:Or},t}(E);var Et={now:function(){return(Et.delegate||Date).now()},delegate:void 0};var wt=function(e){ne(t,e);function t(r,n,o){r===void 0&&(r=1/0),n===void 0&&(n=1/0),o===void 0&&(o=Et);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=n,i._timestampProvider=o,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=n===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,n),i}return t.prototype.next=function(r){var n=this,o=n.isStopped,i=n._buffer,a=n._infiniteTimeWindow,s=n._timestampProvider,f=n._windowTime;o||(i.push(r),!a&&i.push(s.now()+f)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var n=this._innerSubscribe(r),o=this,i=o._infiniteTimeWindow,a=o._buffer,s=a.slice(),f=0;f0?e.prototype.requestAsyncId.call(this,r,n,o):(r.actions.push(this),r._scheduled||(r._scheduled=ut.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,n,o){var i;if(o===void 0&&(o=0),o!=null?o>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,n,o);var a=r.actions;n!=null&&((i=a[a.length-1])===null||i===void 0?void 0:i.id)!==n&&(ut.cancelAnimationFrame(n),r._scheduled=void 0)},t}(Ut);var On=function(e){ne(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var n=this._scheduled;this._scheduled=void 0;var o=this.actions,i;r=r||o.shift();do if(i=r.execute(r.state,r.delay))break;while((r=o[0])&&r.id===n&&o.shift());if(this._active=!1,i){for(;(r=o[0])&&r.id===n&&o.shift();)r.unsubscribe();throw i}},t}(Wt);var we=new On(Tn);var R=new U(function(e){return e.complete()});function Dt(e){return e&&A(e.schedule)}function kr(e){return e[e.length-1]}function Qe(e){return A(kr(e))?e.pop():void 0}function Se(e){return Dt(kr(e))?e.pop():void 0}function Vt(e,t){return typeof kr(e)=="number"?e.pop():t}var pt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function zt(e){return A(e==null?void 0:e.then)}function Nt(e){return A(e[ft])}function qt(e){return Symbol.asyncIterator&&A(e==null?void 0:e[Symbol.asyncIterator])}function Kt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function Ki(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var Qt=Ki();function Yt(e){return A(e==null?void 0:e[Qt])}function Gt(e){return ln(this,arguments,function(){var r,n,o,i;return Pt(this,function(a){switch(a.label){case 0:r=e.getReader(),a.label=1;case 1:a.trys.push([1,,9,10]),a.label=2;case 2:return[4,Xe(r.read())];case 3:return n=a.sent(),o=n.value,i=n.done,i?[4,Xe(void 0)]:[3,5];case 4:return[2,a.sent()];case 5:return[4,Xe(o)];case 6:return[4,a.sent()];case 7:return a.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function Bt(e){return A(e==null?void 0:e.getReader)}function $(e){if(e instanceof U)return e;if(e!=null){if(Nt(e))return Qi(e);if(pt(e))return Yi(e);if(zt(e))return Gi(e);if(qt(e))return _n(e);if(Yt(e))return Bi(e);if(Bt(e))return Ji(e)}throw Kt(e)}function Qi(e){return new U(function(t){var r=e[ft]();if(A(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function Yi(e){return new U(function(t){for(var r=0;r=2;return function(n){return n.pipe(e?_(function(o,i){return e(o,i,n)}):me,Oe(1),r?He(t):zn(function(){return new Xt}))}}function Nn(){for(var e=[],t=0;t=2,!0))}function fe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new E}:t,n=e.resetOnError,o=n===void 0?!0:n,i=e.resetOnComplete,a=i===void 0?!0:i,s=e.resetOnRefCountZero,f=s===void 0?!0:s;return function(c){var u,p,m,d=0,h=!1,v=!1,B=function(){p==null||p.unsubscribe(),p=void 0},re=function(){B(),u=m=void 0,h=v=!1},z=function(){var T=u;re(),T==null||T.unsubscribe()};return g(function(T,Ke){d++,!v&&!h&&B();var We=m=m!=null?m:r();Ke.add(function(){d--,d===0&&!v&&!h&&(p=jr(z,f))}),We.subscribe(Ke),!u&&d>0&&(u=new et({next:function(Ie){return We.next(Ie)},error:function(Ie){v=!0,B(),p=jr(re,o,Ie),We.error(Ie)},complete:function(){h=!0,B(),p=jr(re,a),We.complete()}}),$(T).subscribe(u))})(c)}}function jr(e,t){for(var r=[],n=2;ne.next(document)),e}function K(e,t=document){return Array.from(t.querySelectorAll(e))}function V(e,t=document){let r=se(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function se(e,t=document){return t.querySelector(e)||void 0}function _e(){return document.activeElement instanceof HTMLElement&&document.activeElement||void 0}function tr(e){return L(b(document.body,"focusin"),b(document.body,"focusout")).pipe(ke(1),l(()=>{let t=_e();return typeof t!="undefined"?e.contains(t):!1}),N(e===_e()),Y())}function Be(e){return{x:e.offsetLeft,y:e.offsetTop}}function Yn(e){return L(b(window,"load"),b(window,"resize")).pipe(Ce(0,we),l(()=>Be(e)),N(Be(e)))}function rr(e){return{x:e.scrollLeft,y:e.scrollTop}}function dt(e){return L(b(e,"scroll"),b(window,"resize")).pipe(Ce(0,we),l(()=>rr(e)),N(rr(e)))}var Bn=function(){if(typeof Map!="undefined")return Map;function e(t,r){var n=-1;return t.some(function(o,i){return o[0]===r?(n=i,!0):!1}),n}return function(){function t(){this.__entries__=[]}return Object.defineProperty(t.prototype,"size",{get:function(){return this.__entries__.length},enumerable:!0,configurable:!0}),t.prototype.get=function(r){var n=e(this.__entries__,r),o=this.__entries__[n];return o&&o[1]},t.prototype.set=function(r,n){var o=e(this.__entries__,r);~o?this.__entries__[o][1]=n:this.__entries__.push([r,n])},t.prototype.delete=function(r){var n=this.__entries__,o=e(n,r);~o&&n.splice(o,1)},t.prototype.has=function(r){return!!~e(this.__entries__,r)},t.prototype.clear=function(){this.__entries__.splice(0)},t.prototype.forEach=function(r,n){n===void 0&&(n=null);for(var o=0,i=this.__entries__;o0},e.prototype.connect_=function(){!zr||this.connected_||(document.addEventListener("transitionend",this.onTransitionEnd_),window.addEventListener("resize",this.refresh),xa?(this.mutationsObserver_=new MutationObserver(this.refresh),this.mutationsObserver_.observe(document,{attributes:!0,childList:!0,characterData:!0,subtree:!0})):(document.addEventListener("DOMSubtreeModified",this.refresh),this.mutationEventsAdded_=!0),this.connected_=!0)},e.prototype.disconnect_=function(){!zr||!this.connected_||(document.removeEventListener("transitionend",this.onTransitionEnd_),window.removeEventListener("resize",this.refresh),this.mutationsObserver_&&this.mutationsObserver_.disconnect(),this.mutationEventsAdded_&&document.removeEventListener("DOMSubtreeModified",this.refresh),this.mutationsObserver_=null,this.mutationEventsAdded_=!1,this.connected_=!1)},e.prototype.onTransitionEnd_=function(t){var r=t.propertyName,n=r===void 0?"":r,o=ya.some(function(i){return!!~n.indexOf(i)});o&&this.refresh()},e.getInstance=function(){return this.instance_||(this.instance_=new e),this.instance_},e.instance_=null,e}(),Jn=function(e,t){for(var r=0,n=Object.keys(t);r0},e}(),Zn=typeof WeakMap!="undefined"?new WeakMap:new Bn,eo=function(){function e(t){if(!(this instanceof e))throw new TypeError("Cannot call a class as a function.");if(!arguments.length)throw new TypeError("1 argument required, but only 0 present.");var r=Ea.getInstance(),n=new Ra(t,r,this);Zn.set(this,n)}return e}();["observe","unobserve","disconnect"].forEach(function(e){eo.prototype[e]=function(){var t;return(t=Zn.get(this))[e].apply(t,arguments)}});var ka=function(){return typeof nr.ResizeObserver!="undefined"?nr.ResizeObserver:eo}(),to=ka;var ro=new E,Ha=I(()=>H(new to(e=>{for(let t of e)ro.next(t)}))).pipe(x(e=>L(Te,H(e)).pipe(C(()=>e.disconnect()))),J(1));function de(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ge(e){return Ha.pipe(S(t=>t.observe(e)),x(t=>ro.pipe(_(({target:r})=>r===e),C(()=>t.unobserve(e)),l(()=>de(e)))),N(de(e)))}function bt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function ar(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}var no=new E,Pa=I(()=>H(new IntersectionObserver(e=>{for(let t of e)no.next(t)},{threshold:0}))).pipe(x(e=>L(Te,H(e)).pipe(C(()=>e.disconnect()))),J(1));function sr(e){return Pa.pipe(S(t=>t.observe(e)),x(t=>no.pipe(_(({target:r})=>r===e),C(()=>t.unobserve(e)),l(({isIntersecting:r})=>r))))}function oo(e,t=16){return dt(e).pipe(l(({y:r})=>{let n=de(e),o=bt(e);return r>=o.height-n.height-t}),Y())}var cr={drawer:V("[data-md-toggle=drawer]"),search:V("[data-md-toggle=search]")};function io(e){return cr[e].checked}function qe(e,t){cr[e].checked!==t&&cr[e].click()}function je(e){let t=cr[e];return b(t,"change").pipe(l(()=>t.checked),N(t.checked))}function $a(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Ia(){return L(b(window,"compositionstart").pipe(l(()=>!0)),b(window,"compositionend").pipe(l(()=>!1))).pipe(N(!1))}function ao(){let e=b(window,"keydown").pipe(_(t=>!(t.metaKey||t.ctrlKey)),l(t=>({mode:io("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),_(({mode:t,type:r})=>{if(t==="global"){let n=_e();if(typeof n!="undefined")return!$a(n,r)}return!0}),fe());return Ia().pipe(x(t=>t?R:e))}function Me(){return new URL(location.href)}function ot(e){location.href=e.href}function so(){return new E}function co(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)co(e,r)}function M(e,t,...r){let n=document.createElement(e);if(t)for(let o of Object.keys(t))typeof t[o]!="undefined"&&(typeof t[o]!="boolean"?n.setAttribute(o,t[o]):n.setAttribute(o,""));for(let o of r)co(n,o);return n}function fr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function fo(){return location.hash.substring(1)}function uo(e){let t=M("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function Fa(){return b(window,"hashchange").pipe(l(fo),N(fo()),_(e=>e.length>0),J(1))}function po(){return Fa().pipe(l(e=>se(`[id="${e}"]`)),_(e=>typeof e!="undefined"))}function Nr(e){let t=matchMedia(e);return Zt(r=>t.addListener(()=>r(t.matches))).pipe(N(t.matches))}function lo(){let e=matchMedia("print");return L(b(window,"beforeprint").pipe(l(()=>!0)),b(window,"afterprint").pipe(l(()=>!1))).pipe(N(e.matches))}function qr(e,t){return e.pipe(x(r=>r?t():R))}function ur(e,t={credentials:"same-origin"}){return ve(fetch(`${e}`,t)).pipe(ce(()=>R),x(r=>r.status!==200?Tt(()=>new Error(r.statusText)):H(r)))}function Ue(e,t){return ur(e,t).pipe(x(r=>r.json()),J(1))}function mo(e,t){let r=new DOMParser;return ur(e,t).pipe(x(n=>n.text()),l(n=>r.parseFromString(n,"text/xml")),J(1))}function pr(e){let t=M("script",{src:e});return I(()=>(document.head.appendChild(t),L(b(t,"load"),b(t,"error").pipe(x(()=>Tt(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(l(()=>{}),C(()=>document.head.removeChild(t)),Oe(1))))}function ho(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function bo(){return L(b(window,"scroll",{passive:!0}),b(window,"resize",{passive:!0})).pipe(l(ho),N(ho()))}function vo(){return{width:innerWidth,height:innerHeight}}function go(){return b(window,"resize",{passive:!0}).pipe(l(vo),N(vo()))}function yo(){return Q([bo(),go()]).pipe(l(([e,t])=>({offset:e,size:t})),J(1))}function lr(e,{viewport$:t,header$:r}){let n=t.pipe(X("size")),o=Q([n,r]).pipe(l(()=>Be(e)));return Q([r,t,o]).pipe(l(([{height:i},{offset:a,size:s},{x:f,y:c}])=>({offset:{x:a.x-f,y:a.y-c+i},size:s})))}(()=>{function e(n,o){parent.postMessage(n,o||"*")}function t(...n){return n.reduce((o,i)=>o.then(()=>new Promise(a=>{let s=document.createElement("script");s.src=i,s.onload=a,document.body.appendChild(s)})),Promise.resolve())}var r=class{constructor(n){this.url=n,this.onerror=null,this.onmessage=null,this.onmessageerror=null,this.m=a=>{a.source===this.w&&(a.stopImmediatePropagation(),this.dispatchEvent(new MessageEvent("message",{data:a.data})),this.onmessage&&this.onmessage(a))},this.e=(a,s,f,c,u)=>{if(s===this.url.toString()){let p=new ErrorEvent("error",{message:a,filename:s,lineno:f,colno:c,error:u});this.dispatchEvent(p),this.onerror&&this.onerror(p)}};let o=new EventTarget;this.addEventListener=o.addEventListener.bind(o),this.removeEventListener=o.removeEventListener.bind(o),this.dispatchEvent=o.dispatchEvent.bind(o);let i=document.createElement("iframe");i.width=i.height=i.frameBorder="0",document.body.appendChild(this.iframe=i),this.w.document.open(),this.w.document.write(` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Community Packages

+

Below is a list of packages contributed by the community. These packages normally follow the same installation procedure, however, its best you consult the documentation of the package itself in case there is anything special you need to get it working.

+

Blade package installation

+

Packages will normally come in the form of a composer package that you need to include in your SeAT install, as well as a Service Provider that you need to bootstrap. So, generically speaking, installing a package will mean that you:

+
    +
  • +

    Ensure that you are in the path where you installed. By default, this should be /var/www/seat.

    +
    • +
  • +

    Put your application into maintenance mode. This will ensure that no request from the outside will hit your applications logic, and also help you perform an upgrade uninterrupted. Do this with the following commands issued as the webserver user:

    +
    • +
+
sudo -H -u www-data bash -c 'php artisan down'
+
+
    +
  • Require the package via composer:
    • +
+
sudo -H -u www-data bash -c 'composer require <package vendor>/<package-name>'
+
+
    +
  • Publish the assets with artisan:
    • +
+
sudo -H -u www-data bash -c 'php artisan vendor:publish --force --all'
+
+
    +
  • Run migration in order to update database:
    • +
+
sudo -H -u www-data bash -c 'php artisan migrate'
+
+
    +
  • Renew config and route cache to benefit of newly added functionalities:
    • +
+
1
+2
sudo -H -u www-data bash -c 'php artisan route:cache'
+sudo -H -u www-data bash -c 'php artisan config:cache'
+
+
    +
  • Clear SeAT cache after installation:
    • +
+
sudo -H -u www-data bash -c 'php artisan seat:cache:clear'
+
+
    +
  • Bring your application live and back out of maintenance mode:
    • +
+
sudo -H -u www-data bash -c 'php artisan up'
+
+

Installing packages like this will ensure that none of the core SeAT packages are affected and you should be free to upgrade SeAT core at anytime.

+

Docker package installation

+

Applying community packages to your SeAT instance with Docker requires you to update your .env file located in /opt/seat-docker and uncommenting SEAT_PLUGINS by removing '#' and entering the package(s) to be installed separating each package with a comma. An example of how to enter packages in your .env would be:

+
1
+2
+3
+4
+5
+6
# SeAT Plugins
+# This is a list of the all of the third party plugins that you
+# would like to install as part of SeAT. Package names should be
+# comma seperated if multiple packages should be installed.
+
+SEAT_PLUGINS=denngarr/seat-fitting,cryptaeve/seat-squad-sync
+
+
    +
  • Once you have entered the package(s) to be installed run the below command in /opt/seat-docker:
    • +
+
+
+
+
docker-compose up -d
+
+
+
+
docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+
docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+

After running the above command wait for containers affected to rebuild. If SeAT does not come back up refer to Troubleshooting for more insight.

+

Package list

+

SeAT specific packages

+

Maintained packages

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PackageVersion (SeAT 4.x)Version (SeAT 5.x)InstallationDescription
alliancewaw/seat-mumble-registerLatest Stable VersionSeAT 5.x incompatibleRead the docs This plugin provide an extension to generate a certificate for SeAT user and regist it to mumble server
cryocaustik/seat-hrLatest Stable VersionLatest Unstable VersionHuman Resources plugin for SeAT with Applications (with customized questions per corporation), Blacklist, Intel, Kick History, Notes, and Sheet
cryptaeve/seat-squad-syncLatest Stable VersionSeAT 5.x incompatibleAdds the ability to sync squad members into filters of permissions
cryptaeve/seat-textLatest Stable VersionSeAT 5.x incompatibleA module to serve public static ascii, with editing access controlled by seat
denngarr/seat-fittingLatest Stable VersionSeAT 5.x incompatibleModule to check fittings per character
denngarr/seat-srpLatest Stable VersionSeAT 5.x incompatibleA module for SeAT that tracks SRP requests
h4zz4rddev/seat-buybackLatest Stable VersionSeAT 5.x incompatibleA SeAT module for buyback functionality
humunuk/alliance-structure-mngmtLatest Stable VersionSeAT 5.x incompatibleAdd "Structures" sub-menu to Alliance page and show all the structures that belong to corps in alliance
kassie/calendarLatest Stable VersionSeAT 5.x incompatibleRead the docsCalendar plugin
pyTonicis/seat-corp-mining-taxLatest Stable VersionSeAT 5.x incompatibleRead the docsA Modul to manage corporation mining tax
warlof/seat-discord-connectorLatest Stable VersionLatest Stable VersionRead the docsA Discord driver to be used with seat-connector
warlof/seat-teamspeakLatest Stable VersionLatest Stable VersionRead the docsA Teamspeak driver to be used with seat-connector
recursivetree/seat-infoLatest Stable VersionLatest Stable VersionRead the docsA module that adds a small wiki-like article systems for example as a corporation bulletin.

SeAT 5.x
You need to follow special steps after upgrading to retain your resource files.
recursivetree/seat-ratLatest Stable VersionLatest Stable VersionA module to monitor ratting usage in a system, e.g. to prevent dropping the bounty risk modifier in nullsec.
simplyunnamed/seat-user-last-loginLatest Stable VersionSeAT 5.x incompatibleTool to help find potential AFK's in your corporation.
recursivetree/seat-billingLatest Stable VersionLatest Stable VersionA billing module to help you with ore and rating taxes.
recursivetree/seat-pushx-blamerLatest Stable VersionSeAT 5.x incompatibleA module to tell you who's guilty of blocking the PushX queue.
recursivetree/seat-alliance-industryLatest Stable VersionLatest Stable VersionA corporation/alliance/coalition industry order marketplace
recursivetree/seat-inventoryLatest Stable VersionLatest Stable VersionInventory manager for contracts and corporation hangars.
recursivetree/seat-transportLatest Stable VersionLatest Stable VersionThis plugin is a calculator for hauling costs, for example for an alliance JF service.
recursivetree/seat-mineral-haulingSeAT 4.x incompatibleLatest Stable VersionCalculates the most efficient way to move minerals in refined ore form.
+

Price Provider Packages

+

These packages implement different prices sources for the recursivetree/seat-prices-core price provider system. If you are on SeAT 5 and use a plugin that uses recursivetree/seat-prices-core internally, you can install and use any of the following price provider packages.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Price ProviderVersionDescription
recursivetree/seat-prices-evepraisalLatest Stable VersionPrices from evepraisal clones
recursivetree/seat-prices-evemarketerLatest Stable VersionPrices from evemarketer.com
cryptatech/seat-prices-janiceLatest Stable VersionPrices from https://janice.e-351.com/
cryptatech/seat-prices-fuzzworkLatest Stable VersionPrices from https://market.fuzzwork.co.uk/
+

Library Packages

+

These packages provide utilities for other packages and usually don't need to be installed manually.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
PackageVersionDescription
warlof/seat-connectorLatest Stable VersionA generic connector module that handles invites and roles management with any registered platform
recursivetree/seat-treelibLatest Stable VersionA module that contains shared code for all recursivetree/* plugins
recursivetree/seat-prices-coreLatest Stable VersionThis plugin provides a price provider system for all plugins dealing with prices. Seat 5.x only.
+

Deprecated packages

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PackageVersionDescription
eve-scout/eveseat-oauth2-serverLatest Stable VersionThis EVE SeAT package enables an OAuth2 server for Single sign-on.
flyingferret/seat-whtoolsLatest Stable VersionA small collection of tools for helping with Wh-Life corporation management, including calculating doctrine stocking levels (based on contracts and denngarr/seat-fitting plugin), a blue loot tax calculator, and a skill base certificate management. Currently very much a work in progress.
freedenizen/eveseat-notesLatest Stable VersionA notes addon for seat 1.x
herpaderpaldent/seat-discourseLatest Stable VersionSeAT Discourse enables SeAT to act as SSO provider for your Discourse-Forum instance. Groups and Categories do respect roles of members. With this package you can create hidden sections for your member and public sections for potential recruits to which members get automatically access to. Important: Check installation instructions on Github.
herpaderpaldent/seat-groupsLatest Stable VersionModule to create auto, open and managed role groups to which user can be automatically be assigned, user can opt-in or user can apply to.
herpaderpaldent/seat-notificationsLatest Stable VersionThis is a fully functional notification package for discord and slack notifications. This package is very easily extendable by other packages and should replace core notifications at some point. Currently seat-groups provide many useful notifications. Notifications are send out by slack or discord bot and uses twice a full oAuth2 authentication of the user.
warlof/seat-migratorLatest Stable VersionA migration script between SeAT 2 and SeAT 3
warlof/seat-slack-ssoLatest Stable VersionSlack SSO integration for seat 2.x
warlof/eveseat-mining-ledgerLatest Stable VersionESI capability that provides a mining ledger to SeAT 2.x
warlof/slackbotLatest Stable VersionA slack bot that handles invites and kicks based on an api key
+ + +
+

Danger

+

Packages after this message are provided as history and idea database. They will not work on the stable version since they are non longer maintained by their author or have been integrated in core.

+
+ +

Installing different versions

+

Sometimes it can be useful to install a version different from the latest version, for example if you want to install an older version of a plugin or if you want to test a bugfix. The easiest way to find all available versions is to go to the packagist site of the plugin by clicking on the version in the available plugins list. On packagist, if you scroll down, to the right you will find a list of all available versions.

+
+
+
+

Follow the normal installation steps, but change the composer require command to include the package according to the following example:

+
sudo -H -u www-data bash -c 'composer require <package vendor>/<package-name>:<version-name>'
+
+
+
+

In your .env file, add the version to the package like this:

+

SEAT_PLUGINS=<vendor>/<package>:<version>,cryptaeve/seat-squad-sync:4.0.2
+
+Next, restart the stack as usual.

+
1
+2
docker-compose down
+docker-compose up -d
+
+
+
+

In your .env file, add the version to the package like this:

+

SEAT_PLUGINS=<vendor>/<package>:<version>,cryptaeve/seat-squad-sync:4.0.2
+
+Next, restart the stack as usual.

+
1
+2
docker-compose down
+docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+

In your .env file, add the version to the package like this:

+

SEAT_PLUGINS=<vendor>/<package>:<version>,cryptaeve/seat-squad-sync:4.0.2
+
+Next, restart the stack as usual.

+
1
+2
docker-compose down
+docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/configuration_overload/index.html b/configuration/configuration_overload/index.html new file mode 100644 index 00000000..731d1799 --- /dev/null +++ b/configuration/configuration_overload/index.html @@ -0,0 +1,1403 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Configuration Overload - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

Configuration Overload

+ +

SeAT

+

This page aims to give a brief overview of how configuration is handled in SeAT and its packages. +To give some perspective, we have to have a quick look at how packages are built and bootstrapped.

+

Quick-n-dirty-package summary

+

All of SeAT's core internals are built as packages. This means, every package has a service provider. +All a service provider really is, is a class with 2 methods ie: handle() and register(). +When a service provider is bootstrapped into the application, these 2 methods are called at some stage.

+

It is in these methods that we tell the Laravel framework more about our package. +Amongst many things that we can tell it, one of them is configuration related. +All we really telling the application is where the configuration file is, and under which namespace does it live. +Another important fact is that SeAT package configurations are added with the mergeConfigFrom() method. +This means, you can override the defaults in your installation without worrying about breaking the package itself.

+

Overriding configuration

+

Lets take a look at a sample package configuration file: The eveseat/eveapi package for example. +At the time of this writing, it has 5 configuration options. The first being a version, the last being eseye_loglevel. +When this package is installed, this configuration file will live somewhere deep inside your vendor folder. +Changing the value there is not impossible, but it will be lost with the next package upgrade. +The better method will be to override the change locally, inside you config/ folder here.

+

An example, changing eseye_loglevel

+

To start, create the file eveapi.config.php inside the config folder. +Next, we add the contents in the file to return an array, specifying the eseye_loglevel key and its new value. +The file would look something like this:

+
1
+2
+3
+4
+5
+6
+7
<?php
+
+// File: config/eveapi.config.php
+
+return [
+    'eseye_loglevel' => 'debug',
+];
+
+

That's it. The configuration should now have been overridden.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/email_setup/gmail/index.html b/configuration/email_setup/gmail/index.html new file mode 100644 index 00000000..9dd8576e --- /dev/null +++ b/configuration/email_setup/gmail/index.html @@ -0,0 +1,1384 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + GMail - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Email Setup - Using GMail

+

Introduction

+

SeAT requires email to be setup to allow for things like notifications to be sent. +This guide will attempt to describe how to go about setting up your email using GMail as an SMTP.

+

The config

+

As with anything Laravel, the config for your email setup will live in your installs .env file. To use GMail as an SMTP service, set the MAIL_DRIVER option in your .env configuration file to smtp. Next, specify the SMTP details:

+
1
+2
+3
+4
+5
+6
+7
+8
+9
// File: .env
+
+MAIL_DRIVER=smtp
+MAIL_HOST=smtp.gmail.com
+MAIL_PORT=587
+MAIL_USERNAME=username@gmail.com
+MAIL_PASSWORD=gmailpassword
+MAIL_ENCRYPTION=tls
+MAIL_FROM_ADDRESS=username@gmail.com
+
+

Done! To test, you can add some mail notification using the Integrations and Notification groups.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/email_setup/mailgun/index.html b/configuration/email_setup/mailgun/index.html new file mode 100644 index 00000000..b2c9284f --- /dev/null +++ b/configuration/email_setup/mailgun/index.html @@ -0,0 +1,1382 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Mailgun - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Email Setup - Using Mailgun

+

Introduction

+

SeAT requires email to be setup to allow for things like notifications to be sent. +This guide will attempt to describe how to go about setting up your email using the Mailgun service. +Though Mailgun is a commercial service, you get to send 10k emails for free per month. +It also provides epic stats for you to track emails with etc.

+

The config

+

As with anything Laravel, the config for mailgun will live in your installs .env file. +To use the Mailgun driver, first set the MAIL_DRIVER option in your .env configuration file to mailgun. +Next, we will add two options to specify details about our mailgun account.

+
1
+2
+3
+4
// File: .env
+
+MAILGUN_DOMAIN=whateveritis
+MAILGUN_SECRET=anotherthing
+
+

To find out the values you need to populate, login to your mailgun account and browse to the domains section. +Pick the applicable domain name. The screen you will see should looks something similar to this:

+

Mailgun Domain

+

The big title (sandbox1XXXXXXX in my case) is the domain name, and the field titled API Key is the MAILGUN_SECRET.

+

Done! To test, you can add some mail notification using the Integrations and Notification groups.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/env_file_reference/index.html b/configuration/env_file_reference/index.html new file mode 100644 index 00000000..10e029ea --- /dev/null +++ b/configuration/env_file_reference/index.html @@ -0,0 +1,1452 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Env File Reference - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Env Reference

+

In both the case of a Docker installation as well as a host based installation (manual or via SeAT tool), SeAT has some configuration values that can be set via an .env file. Depending on your installation type, this file will be in either /opt/seat-docker/.env or in /var/www/seat/.env

+

Configuration Value Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter NameDefault valueDescription
APP_URLhttp://seat.localThis is the public address where SeAT instance is reachable. That should match with the EVE_CALLBACK_URL without /auth/eve/callback suffix
DB_HOST127.0.0.1This is the IP or domain from your SQL Server.
DB_PORT3306This is the port used by your SQL Server to receive query.
DB_DATABASEseatThis is the name for your SeAT database.
DB_USERNAMEseatThis is the user which is granted to the SeAT database from SeAT server.
DB_PASSWORDsecretThis is the user password
MAIL_DRIVERsmtpThis is the driver used to send mail. It will be covered in a dedicated article.
MAIL_HOSTsmtp.mailtrap.ioThis is driver mail hostname. It will be covered in a dedicated article.
MAIL_PORT2525This is the driver mail port. It will be covered in a dedicated article.
MAIL_USERNAMEnullThis is the driver mail username. It will be covered in a dedicated article.
MAIL_PASSWORDnullThis is the driver mail password. It will be covered in a dedicated article.
MAIL_ENCRYPTIONnullThis is the driver mail encryption. It will be covered in a dedicated article.
MAIL_FROM_ADDRESSnoreply@localhost.localThis is the mail address which the user will chown when he will receive mail from SeAT.
MAIL_FROM_NAMESeAT AdministratorThis is the name which the user will chown when he will receive mail from SeAT.
EVE_CLIENT_IDnullThis is the EVE Application Client ID you'll get when you created an application over https://developers.eveonline.com
EVE_CLIENT_SECRETnullThis is the EVE Application Client Secret you'll get when you created an application over https://developers.eveonline.com
EVE_CALLBACK_URLhttps://seat.local/auth/eve/callbackThis is the EVE Application Callback URL you filled when you created an application over https://developers.eveonline.com. You should have only to fix seat.local
QUEUE_BALANCING_MODEfalseDetermine the workers balancing mode used by the Jobs Manager. Value can be false, auto or simple. See official Laravel documentation for more details
QUEUE_WORKERS4Determine the amount of worker which have to be spawn to process jobs over all queues. In auto and simple balancing, this value cannot be lower than 4 as it's correspond to the available queues.
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/esi_configuration/index.html b/configuration/esi_configuration/index.html new file mode 100644 index 00000000..51a6c170 --- /dev/null +++ b/configuration/esi_configuration/index.html @@ -0,0 +1,1471 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + ESI Configuration - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Configuring Eve Online ESI-Scopes

+

Introduction

+

For normal operations within SeAT, authentication is provided by EVE Onlines' SSO service and API access with ESI and tokens supplied via SSO. Technical details behind the SSO implementation can be found here.

+

Authenticating users using SSO effectively means that users may authenticate to SeAT using their existing EVE Online credentials. SeAT does not have access to the credentials itself as that is handled entirely by CCP. Only once authentication is successful from an EVE Online perspective does a user get asked if they want to allow your SeAT installation to have access with the configured set of scopes. Once the user agrees to these scopes, the users browser is redirect back to SeAT and will be logged in.

+

If you have not configured this yet, the login page will present you with a warning about it:

+

initial login screen

+

Configuration Summary

+

A bit of setup work is needed in order to have your SeAT setup ready for SSO integration and ESI usage. The gist of it is:

+ +

Register your application

+

Browse to the EVE Online Developers portal and create a new Application.

+

new sso application

+

Give your application a meaningful Name and a Description. Users will see this name when they review the access Third Party applications have to their account so keep that in mind when registering your application.

+

new sso application

+

Next, set the connection type to Authentication & API Access (1), select the ESI Scopes you want (probably all of them) (2) and specify the Callback URL (3)

+

To select ESI Scopes you can search for them in Available Scopes (2) and select the desired scope. The selected scope then will moved to (3).

+

new sso application

+
+

Note on the Callback URL

+

The Callback URL where the user should be redirected to once authentication was successful. In other words, once they have completed authentication using their EVE Online credentials, they need to be redirected back to your SeAT instance. In the example above, we can see it is https://seat.local/auth/eve/callback. You should replace the seat.local part with your domain!

+

For example, assuming you are hosting SeAT at https://this.is.seat/, then the Callback URL will be https://this.is.seat/auth/eve/callback. If you have SeAT in a sub folder on your web server, remember to add the folder name before /auth/eve/callback.

+
+

With the new application created, you will now have the EVE_CLIENT_ID, EVE_CLIENT_SECRET that you need to configure in SeAT itself. Take note of these values.

+

new sso application

+

Set config parameters in .env file

+

We are almost done. The next thing to do is to add the configuration parameters to our SeAT installs .env file. Browse to your SeAT installation directory and edit the .env file (note this is a hidden file and wont show up when you just type ls).

+

Look for the following section of the file and populate the values with those you got when you created an application on the developers site:

+
1
+2
+3
EVE_CLIENT_ID=null
+EVE_CLIENT_SECRET=null
+EVE_CALLBACK_URL=http://seat.test/auth/eve/callback
+
+

Notes for Docker Users

+

Your .env file is located in /opt/seat-docker. Rebuild your app after setting the ESI Details in it using:

+
+
+
+
1
+2
docker-compose down
+docker-compose up -d
+
+
+
+
1
+2
docker compose down
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+
1
+2
docker compose down
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/eve_administrative_contact/index.html b/configuration/eve_administrative_contact/index.html new file mode 100644 index 00000000..fab0aa58 --- /dev/null +++ b/configuration/eve_administrative_contact/index.html @@ -0,0 +1,1427 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + EVE Administrative Contact - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Eve API Administrative Contact

+

What

+

Requests to the EVE API need to have an administrative contact email set before SeAT will queue jobs to process. CCP made the request in this Github issue. To address this, the email address is added to the User-Agent string that is used when making EVE API requests as can be seen eveseat/eveapi:Helpers/PhealSetup#L77.

+

Why

+

The error Failed to queue due to default config is generated by eveseat/eveapi:Traits/JobManager#L47-L56 check. In order for this check to pass, you need to configure the administrative email address in the SeAT configuration.

+

How

+

Adding the email address can be done in two ways. Wither via the command line or via the Web interface.

+

Web interface

+

The other method to change the admin email is via the web interface. You need to be logged in with a user that has the superuser role. Typically, if the email address is not set, you may notice the following warning on the home page:

+

seat default email warning

+

To configure it, browse to Configuration -> SeAT Settings from the side menu, and set the email in the Administrator Email field.

+

seat webui email config

+

Command line

+

The command php artisan seat:admin:email will prompt you to add a valid email address for the administrative contact:

+

Example:

+

seat admin email

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/configuration/sde_overload/index.html b/configuration/sde_overload/index.html new file mode 100644 index 00000000..470f723d --- /dev/null +++ b/configuration/sde_overload/index.html @@ -0,0 +1,1351 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + SDE Overload - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SDE Overload

+ +

SeAT

+

SeAT sources information about the SDE from a json file hosted here. It may happen that the SDE gets updated but the the json resource has not yet been updated. For this reason, its possible to specify the version to get based on what is available on www.fuzzwork.co.uk.

+

Overriding the resources json

+

Check the version of SDE dumps available on www.fuzzwork.co.uk. At the time of this writing, frostline-1.0-116241 was the latest. Once you have the version string ready, open the .env configuration file and add a key as follows:

+
SDE_VERSION=frostline-1.0-116241
+
+

When running the SDE updater, specify the --local parameter to source the version string from the configuration file:

+
php artisan eve:update:sde --local
+
+
+

Info

+

By default, SeAT automatically updates the SDE every month. You may want to login as an administrator and remove the schedule to update it monthly if you have overridden the default.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/css/extra_footer.css b/css/extra_footer.css new file mode 100644 index 00000000..37900e49 --- /dev/null +++ b/css/extra_footer.css @@ -0,0 +1,3 @@ +.md-footer-nav { + display: none; +} diff --git a/css/extra_typo.css b/css/extra_typo.css new file mode 100644 index 00000000..aae4f6d0 --- /dev/null +++ b/css/extra_typo.css @@ -0,0 +1,33 @@ +.md-typeset img, .md-typeset svg { + display: block; + margin-left: auto; + margin-right: auto; +} + +.md-typeset__table { + display: table; + width: 100%; +} + +.md-typeset table:not([class]) { + display: table; +} + +.md-typeset table:not([class]) td { + vertical-align: middle; +} + +[data-md-color-primary="grey"] .md-typeset a { + color: #ffa724; +} + +div.md-content li, div.md-content p { + text-align: justify; +} + +.md-typeset__scrollwrap { + text-align: center; +} +.md-typeset ul { + list-style-type: square; +} diff --git a/developer_guides/core_package_breakdown/index.html b/developer_guides/core_package_breakdown/index.html new file mode 100644 index 00000000..db6958a4 --- /dev/null +++ b/developer_guides/core_package_breakdown/index.html @@ -0,0 +1,1467 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Core Package Breakdown - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Developers Guides - Core Package Breakdown

+

Understanding the core SeAT packages

+

This section aims to describe the functional differences between the various SeAT packages.

+

eveseat/api

+

Namespace: Seat\Api

+

Source Code: link

+

This repository contains all the SeAT Api Endpoints, as well as the routes and views for API key management.

+

eveseat/eveapi

+

Namespace: Seat\Eveapi

+

Source Code: link

+

This repository is the heart of the API update logic. It is responsible for doing the actual update work, pulling the EVE API documents from ESI, parsing them and storing the resultant data in the database. Most of the data models live in this repository too.

+

eveseat/notifications

+

Namespace: Seat\Notifications

+

Source Code: link

+

This repository contains a set of scheduled jobs that perform notifications type tasks. A notification can be something as simple as an alert about a corporation member that has been inactive for a period of time.

+

eveseat/web

+

Namespace: Seat\Web

+

Source Code: link

+

This repository contains the web interface for SeAT. It contains by far the most complex service provider and will undoubtedly become the prime example/reference when developing packages for SeAT. This package is also the only one that has a permissions / ACL concept. Refer the to the permissions document for more information.

+

eveseat/seat

+

Namespace: App

+

Source Code: link

+

This is the main SeAT repository. It does not really contain much logic. In fact, it should just be seen as the glue between all the core packages. This is the repository that is cloned when a new installation is done.

+

The most important part of this repository is the service providers that are bootstrapped with the application. The providers array has the default Laravel providers as well as the SeAT providers at the end. These providers tell the application where to find routes, views, configs etc. For more detailed information about providers, refer to the Laravel 5.5 documentation. When you write your package though, you should make use of package discovery as described in the Laravel 5.5 documenation. This will make the installation of your package super simple without the need to edit any files.

+

eveseat/services

+

Namespace: Seat\Services

+

Source Code: link

+

This repository contains 'services'. A service is defined as any form of helper and or repository that other packages can depend on. The eveseat/web package (amongst others) make heavy use of the repository classes in this package.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/developer_installation/index.html b/developer_guides/developer_installation/index.html new file mode 100644 index 00000000..a665c2cb --- /dev/null +++ b/developer_guides/developer_installation/index.html @@ -0,0 +1,1447 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Developer Installation - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Developer Installation

+

Since SeAT 4 and including SeAT 5, starting with Docker build 4.1.0, spawning a development environment has been made easier. +You can use the same image as of production environment - either you're working on core packages or third party ones.

+

General

+

First, start with standard installation to get a working environment.

+

The official docker-compose wrapper is shipped with a packages directory. +It is mounted readonly, and you can store your development sources in it.

+

To make things easier, we recommend you keep vendor path convention to split your sources across every single package you want to play with.

+

Developing plugins and core packages doesn't differ at all, modules installed in the packages directory always take priority. +In the case of core modules, this means the version from packages and not the version provided by the docker container will be used.

+

Overrider

+

The image has been designed to look for a file called override.json inside packages directory. +When it is found, it will be merged together with standard composer.json file from eveseat/seat package.

+

It's designed to override both autoload and providers. +Here is a complete override.json structure:

+
1
+2
+3
+4
+5
+6
+7
+8
{
+  "autoload": {
+    "namespace_to_load\\": "packages/sources_path"
+  },
+  "providers": [
+    "FQCN\\Provider"
+  ]
+}
+
+

An override can have either autoload, providers or even both property. +Do not forget to escape \ in order to get a valid json file.

+

When your container will start, mapping from autoload property in your override.json file will be merged with autoload-dev property from official composer.json.

+
+

SeAT 4.x

+
    +
  1. If you need access the console of any container, access it via docker exec seat-web sh where seat-web is the name of the target container.
    2. +
  2. You can execute artisan commands from outside of docker with docker exec seat-web php artisan <command>
    3. +
+
+
+

SeAT 5.x

+
    +
  1. If you need access the console of any container, access it via docker exec front sh where front is the name of the target container.
    2. +
  2. You can execute artisan commands from outside of docker with docker exec front php artisan <command>
    3. +
+
+

Please note that there is currently no way to install dependencies with the package override.

+

Teach things by example

+

As an example, let's say I want to make a new feature in web core package, I'll spawn an eveseat directory at root packages directory, followed by a clone from eveseat/web git repository. +Last but not least, I'll create an override.json file to inform SeAT there are developer things to load.

+
    +
  1. Create vendor directory into packages directory mkdir packages/eveseat
    2. +
  2. Cloning core web package into packages/eveseat/web directory git clone https://github.com/eveseat/web.git packages/eveseat/web
    3. +
  3. Create an override.json to use custom web sources
    4. +
+
1
+2
+3
+4
+5
+6
+7
cat > packages/override.json << EOL
+{
+  "autoload": {
+    "Seat\\Web\\": "packages/eveseat/web/src/"
+  }
+}
+EOL
+
+
+

Tips

+

If you're working with Windows, prefer to store your files in wsl layer rather than Windows directory. +Both work, however, you'll get better performances!

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/development_tips/index.html b/developer_guides/development_tips/index.html new file mode 100644 index 00000000..54bd3a8e --- /dev/null +++ b/developer_guides/development_tips/index.html @@ -0,0 +1,1380 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Development Tips - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Development Tips

+

This page contains general tips and tricks that may be useful during package development.

+

Best practices

+

No doubt, there are no limits to what code you can write, how you structure it and how you name things. However, the last thing you want is to have conflicts with the SeAT core, or someone elses package! The following list contains some tips to help you avoid those conflicts and to help people better discover your packages:

+
    +
  • Prefix your github repository name with seat eg: seat-teamspeak.
    • +
  • Tag your github repository with seat.
    • +
  • Use a unique package namespace such as Author\Seat\Package\ eg: Warlof\Seat\Teamspeak\.
    • +
  • Prefix your database table names with something unique to your package. eg warlof_teamspeak_users. + Although you shouldn't make your prefix too long, as there is a 64 character table length limit.
    • +
  • Do not modify core tables. This will break future updates for users of your package.
    • +
  • Prefix your settings with both an author and package eg: warlof.teamspeak.address.
    • +
  • Prefix redis records with both author and package eg: warlof.teamspeak.channels.
    • +
  • In your composer.json file, set the type to seat-plugin.
    • +
  • Avoid altering core tables, especially introducing relationship - this might break core migrations. Prefer to use observer if you need to maintain your data across core models.
    • +
  • If you need an API or something the SeAT core doesn't provide, consider contributing it. The SeAT core is not set in stone.
    • +
  • Scope your routes: For example all routes from the seat core start with seatcorelike this: seatcore::my.route.to.someting. You should follow a similar format: seat<plugin name>::<route>
    • +
+

Model Observers

+

Depending on what your package does, it may be interesting for you to know when data is created / deleted. Given that SeAT makes use of Laravel, you have the ability to subscribe to events that occur on any model within SeAT.

+

For example, should a User model get deleted, the deleted event will get fired. Writing an observer class and subscribing to it with \Seat\Web\Models\User::observer(\My\Namespace\UserObserver::class) will allow you to define a deleted() method inside of your observer class and perform extra logic with the User that got deleted.

+

Examples of where this may be interesting could be if you need to have cleanup code for tables that your package includes.

+

For more information, checkout the Laravel documentation on Eloquent Observers.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/job_queue_flow/index.html b/developer_guides/job_queue_flow/index.html new file mode 100644 index 00000000..11cf3597 --- /dev/null +++ b/developer_guides/job_queue_flow/index.html @@ -0,0 +1,1323 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Job Queue Flow - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Job Queue Flow

+

When a job is queued, it's instance is serialized and push into the Redis database. +Horizon, our jobs orchestrator is taking care of every new jobs falling in redis and push it to an available worker from the targeted queue.

+

With SeAT 4, queues have been renamed and are scoped. This helps to identify load per "topic" and ensure better parallel processing of jobs.

+

As shown bellow, queues characters, corporations and public are dedicated to ESI jobs.

+
    +
  • Characters queue is processing all jobs directly tied to a character entity (like info, assets, contracts, etc...)
    • +
  • Corporations queue is processing all jobs directly tied to a corporation entity (like killmails, jobs, wallets, etc...)
    • +
  • Public queue is processing all jobs related to universe (like stations, alliances, sovereignties, etc...)
    • +
+

There is a dedicated queue to handle notifications tasks (like notifying a killmail on Discord). +So, you will always get your notifications as fast as possible.

+

The last two other queues (high and default) have a general purpose.

+
    +
  • The high queue is dedicated to jobs which have a critical level (like those related to security)
    • +
  • The default queue is a bucket collecting all jobs without any other specified queue
    • +
+

The default (and recommended) jobs handling configuration is using auto balancing. +This ensures every single queue always have a minimum of workers (1 is the default value).

+
+

Important

+

There are no ranking in queues, so, the high one is not most important than other in the way jobs are processing. +Queue name doesn't influe on their ability to process load. So, please use high queue for really important/critical tasks only.

+
+

Flow

+

An editable draw.io xml to import can be found here: seat_jobs_flow.drawio

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/notifications_implementation/index.html b/developer_guides/notifications_implementation/index.html new file mode 100644 index 00000000..4fe9303b --- /dev/null +++ b/developer_guides/notifications_implementation/index.html @@ -0,0 +1,1586 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Notifications Implementation - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Developers Guides - Notifications Implementation

+
+

Seat 5

+

This guide is already updated for seat 5. Older versions of this guide can be found on github.

+
+

Introduction

+

SeAT is shipped with a built-in notification system which is able to send message across the world to almost any platform.

+

It is supporting e-mail, Slack and Discord out of the box.

+

However, thanks to Laravel, if you need to support another platform - you simply need to implement the related driver. See official Laravel Notification Channels website to get more about this.

+

Additionally, there is a system to mention certain users when a notification gets sent. Since we don't assume that many people need to implement this for a new platform, there is no written documentation. This is a good starting point to read the code: Config/notifications.mentions.php

+

Configuration

+

All notifications must be declared inside notifications.alerts.php. You will want to create a file named like this in the Config directory of your plugin and then use mergeConfigFrom in your service provider to merge the seat core and plugin notification configuration. +Every entry must follow this pattern:

+
1
+2
+3
+4
+5
+6
+7
'created_user' => [
+    'label' => 'notifications::alerts.created_user',
+    'handlers' => [
+        'mail' => \Seat\Notifications\Notifications\Seat\Mail\CreatedUser::class,
+        'slack' => \Seat\Notifications\Notifications\Seat\Slack\CreatedUser::class,
+    ],
+]
+
+
    +
  • the entry key created_user must be unique overall system and will identify the very specific notification declaration. It will reference the notification definition composed of label and handlers keys.
    • +
  • the label will reference a translation token - this is the value which will appear on user interface into notification settings
    • +
  • the handlers key is containers a list of available formatters. There is a formatter per available platform - or so called - channel.
    • +
  • the optional visible key hides the notification from the list of available notifications, but you can still use the seat notification infrastructure normally. Realistically, you don't need this for anything.
    • +
+

You can also look at the seat core notifications.alerts.php file as an example.

+

Formatters

+

Formatters are class which will define how message targeting a specific channel must be structured. +In upper example, we have two formatters:

+ +

Formatter must extend a different abstract class depending on what kind of platform it supports:

+
    +
  • Discord: Seat\Notifications\Notifications\AbstractDiscordNotification
    • +
  • Slack: Seat\Notifications\Notifications\AbstractSlackDiscordNotification
    • +
  • Mail: Seat\Notifications\Notifications\AbstractMailNotification
    • +
+

Every formatter is composed of the following method:

+
    +
  • populateMessage(Message $message, mixed $notifiable) which will generate the structure message for the target platform. The type of Message differs slightly according to which platform you're on, e.g. on discord it is a Seat\Notifications\Services\Discord\Messages\DiscordMessage, on slack it is a Illuminate\Notifications\Messages\SlackMessage.
    • +
+

Observers

+

In SeAT, notifications are event based and sent by jobs queued in notifications queue. This prevents to lock system while sending the information.

+

To send your notification, you will listen for system events (ie: a character notification created in the database) in order to dispatch the selected notification.

+

Characters

+

All characters related notifications are handled by \Seat\Notifications\Observers\CharacterNotificationObserver

+

It is waiting for an Eve Online notification targeting a character to be registered and dispatch the related message to the requested platform - if asked for.

+

SeAT is shipped with numerous notifications - but due to the number of existing ones and the fact that there are regularly news notifications created by CCP attached to added features, it might append that a notification isn't handled.

+

You can track such cases using debug log level which will generate a log entry looking like this:

+
+

Unsupported notification type.\ + type: TheNotificationTypeAsPerESIDefinition (see: https://esi.evetech.net/ui/#/Character/get_characters_character_id_notifications)\ + sender_type: character\ + notification: the YAML structure of the notification

+
+

You'll find all standard notifications handler related to character into the following namespace: \Seat\Notifications\Notifications\Characters

+

Corporations

+

Most of the corporations related notifications are handled by \Seat\Notifications\Observers\CharacterNotificationObserver

+

It is waiting for an Eve Online notification targeting a corporation to be registered and dispatch the related message to the requested platform - if asked for.

+

SeAT is shipped with numerous notifications - but due to the number of existing ones and the fact that there are regularly news notifications created by CCP attached to added features, it might append that a notification isn't handled.

+

You can track such cases using debug log level which will generated a log entry looking like this :

+
+

Unsupported notification type.\ + type: TheNotificationTypeAsPerESIDefinition (see: https://esi.evetech.net/ui/#/Character/get_characters_character_id_notifications)\ + sender_type: corporation\ + notification: the YAML structure of the notification

+
+

Alternatively, notifications related to corporation member state are handled by \Seat\Notifications\Observers\CorporationMemberTrackingObserver

+

You'll find all standard notifications handler related to corporation into the following namespace: \Seat\Notifications\Notifications\Corporations

+

Killmails

+

All killmails related notifications are handled by \Seat\Notifications\Observers\KillmailNotificationObserver

+

It is waiting for a killmail being registered and dispatch the related message to the requested platform - if asked for.

+

Squads

+

All squads related notifications are handled by \Seat\Notifications\Observers\SquadApplicationObserver and \Seat\Notifications\Observers\SquadMemberObserver

+

It is waiting for squads members and applications to be registered and dispatch the related message to the requested platform - if asked for.

+

You'll find all standard notifications handler related to Squads into the following namespace: \Seat\Notifications\Notifications\Seat

+

Users

+

All users related notifications are handled by \Seat\Notifications\Observers\UserObserver

+

It is waiting for a user to be registered and dispatch the related message to the requested platform - if asked for.

+

You'll find all standard notifications handler related to character into the following namespace: \Seat\Notifications\Notifications\Seat

+

Porting Plugins from Seat 4 to 5

+

All notifications continue to work without any changes, even though there have been major refactors. However, to profit of the new mentions system behind discord pings, you need to change a few things to update to the new notification structure:

+
    +
  • Start extending from the platform specific classes instead of Seat\Notifications\Notifications\AbstractNotification.
    • +
  • Discord: extend Seat\Notifications\Notifications\AbstractDiscordNotification
    • +
  • Slack: extend Seat\Notifications\Notifications\AbstractSlackDiscordNotification
    • +
  • Mail: extend Seat\Notifications\Notifications\AbstractMailNotification
    • +
  • Remove the via method. It moved to the abstract notification class.
    • +
  • Refactor your public toX() method to a protected populateMessage(Messagetype $message, $notifiable). Instead of creating a new message, use the parameter $message. The type Message must be adjusted depending on your platform:
    • +
  • discord: Seat\Notifications\Services\Discord\Messages\DiscordMessage
    • +
  • slack: Illuminate\Notifications\Messages\SlackMessage
    • +
  • mail: Illuminate\Notifications\Messages\MailMessage
    • +
  • Consider using the Seat\Notifications\Traits\NotificationDispatchTool trait to dispatch notification. It helps to deduplicate the most common logic.
    • +
+

The old plugin structure will stop working in seat 6.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/package_development/index.html b/developer_guides/package_development/index.html new file mode 100644 index 00000000..6a72447d --- /dev/null +++ b/developer_guides/package_development/index.html @@ -0,0 +1,1924 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Package Development - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Developers Guides - Package Development

+

Introduction

+

So, you want to write a SeAT package? Hopefully this guide helps you along the way! This guide was written while writing the API package for SeAT here. I figured it would be best to try and capture the process to help in case I miss any important details.

+

Be sure to also have a look at the Development Tips page!

+

Background notes

+

I think its important to keep in mind a few things about how SeAT is put together. The most important being a brief description of what each core package offers, and how you can integrate with them. For a breakdown on what the core packages provide, please refer the to [breakdown].

+

SeAT 4 is written on Laravel 6, while SeAT 5 uses Laravel 10. A very good thing to do would be to actually read the documentation top->bottom and get an idea of what is possible with the framework. SeAT core packages make heavy use of many of the features, based directly of what has been interpreted by this very documentation.

+

If you really want to start contributing packages, but just cant get your head around this whole Laravel thing, then I can suggest you have a look at this excellent free course material covering the basics of what you will encounter in the SeAT codebase. https://laracasts.com/series/laravel-6-from-scratch

+

Other plugins and the SeAT core are also a good learning resource.

+

Getting started

+

The very first thing to do is prepare the empty git repository on say Github, as well as the composer package itself. Clone a clean repository, and run composer init, answering any questions. Once that is done, edit the resultant composer.json and prepare the autoload block. SeAT core follows the PSR-4 autoloading standard. I will suggest you do the same. For some more detailed composer info, refer to the docs here. For the API package, I am going to autoload Seat\Api from the src directory using PSR-4.

+

Service provider

+

As mentioned in the package breakdowns, the eveseat/seat repository bootstraps packages via service providers or package discovery. This is actually a Laravel convention that SeAT just follows. To get our package ready, we need to create a service provider. For the API package, I create an ApiServiceProvider class in src/ directory which extends Seat\Services\AbstractSeatPlugin. Our packages file structure now looks as follows:

+
1
+2
+3
├── composer.json
+└── src
+    └── ApiServiceProvider.php
+
+
+

Hint

+

The AbstractSeatPlugin class is extending Laravel ServiceProvider class and ship you with useful methods that help to register your plugin in the stack (including version discovery, permissions registration, etc...). +You must use it rather than the standard one, especially if you want permissions and get your packages in Settings > SeAT Settings > SeAT Module Versions pane.

+
+

Package structure

+

From here you pretty much free to do what you want. How you structure the package will obviously depend on what exactly your package provides. In principle, I prefer to follow the same package structure as Laravel does for web / console features. Since we are going to be providing web features with the API, we will quickly create a few folders in preparation for this. I know beforehand that we are going to need a model to store API tokens; middleware to authenticate API requests; routes and controllers for the actual api logic (preferably making use of the eveapi/services repository classes for data access) as well as a few web views for administrators to generate API tokens for applications. With that in mind, the initial structure looks as follows:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
├── composer.json
+└── src
+    ├── ApiServiceProvider.php
+    ├── Config
+    ├── Http
+    │   ├── Controllers
+    │   └── Middleware
+    ├── Models
+    ├── database
+    │   └── migrations
+    └── resources
+        └── views
+
+

This will obviously change as we progress building the package.

+

Routes and controllers

+

To start testing the API, we need to add a route and controller to process some requests and responses. My routes.php file will have a global Route::group() to encapsulate the routes in the Seat\Api namespace as well as prefix them with api/.

+
1
+2
+3
+4
+5
+6
+7
// File: routes.php
+Route::group([ 'namespace' => 'Seat\Api\Http\Controllers',
+    'prefix' => 'api'
+], function () {
+
+    // Logic here
+});
+
+

See the final product here for a more complete example.

+

Next, I add some logic with a route to /, update the base frameworks composer.json to autoload the Seat\Api namespace from the directory where my package lives, run composer dump-autoload and add the service provider to the eveseat/seat repositories app.php providers array. Lastly, I add a method to the service provider to load the routes and call it form the boot() method in the generated stub.

+

See the complete service provider here

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
/**
+* Include the routes
+*/
+public function add_routes()
+{
+
+    if (!$this->app->routesAreCached()) {
+        include __DIR__ . '/Http/routes.php';
+    }
+}
+
+

As a final test, I check that my route is accessible from a booted SeAT app. :)

+

Routes

+

Access Control

+

Obviously, some routes are not for everyone's eyes. SeAT comes with middleware that can be used to filter out requests that may not be authorized for your route. As can be seen in the example below (from here), we are filtering out requests to api-admin for only superusers.

+
1
+2
+3
+4
+5
+6
+7
+8
+9
Route::group([
+        'namespace'  => 'Admin',
+        'middleware' => ['auth', 'can:global.superuser'], // The ACL specification.
+        'prefix'     => 'api-admin'
+    ], function () {
+        Route::get('/', [
+            'as'   => 'seatcore::api-admin.list',
+            'uses' => 'ApiAdminController@listTokens']);
+    });
+
+

I suggest you have a look at the eveseat/web packages routes definitions for more examples on how the middleware is used. https://github.com/eveseat/web/tree/master/src/Http/Routes

+

It is recommended that you scope the route name defined in 'as' => 'seatcore::api-admin.list'. For example all routes from the seat core start with seatcore like this: seatcore::my.route.to.someting. You should follow a similar format: seat<plugin name>::<route>

+

Middleware

+

To auth our API requests, we are going to go with token based authentication for now. We want users to present us with a X-Token header (from a valid allowed src IP address) before they may proceed with their request. To do this, we will filter requests using middleware. Thankfully, again, Laravel comes with a command to stub us some empty middleware. Run php artisan make:middleware ApiToken and copy it to your projects Middleware folder. Next we should register the middleware in our service provider. I do this by adding a method and calling it in boot().

+

See the complete middleware here

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
/**
+ * Include the middleware needed
+ *
+ * @param $router
+ */
+public function add_middleware($router)
+{
+
+    // Authenticate checks that the token is valid
+    // from an allowed IP address
+    $router->middleware('api.auth', ApiToken::class);
+
+}
+
+

Views

+

Although almost all of our interfacing with this package will be via the json api endpoints, we need to add a few routes that will give an administrator the ability to generate API tokens as well as view logs etc. This will be for an administrator, so we will re-use the ACL features provided by the eveseat/web package to ensure that only admins an access our api-admin routes. Views live in resources/views and are bootstrapped to the api namespace in the service provider. See the service provider here for an example.

+

Note how we are re-using views that exist in the web namespace. All we have to do is extend one of the grids like here and start without our blade template.

+ +

Integrating with the sidebar is also really easy. All you have to do is create a config file, bootstrap it in the service provider and viola. The config file itself has a set structure for the web package to interpret and can be seen here.

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
return [
+    'api' => [
+        'permission'    => 'global.superuser',
+        'name'          => 'Api Tokens',
+        'icon'          => 'fas fa-exchange',
+        'route_segment' => 'api-admin',
+        'entries'       => [
+            [   // Manage API Tokens
+                'name'  => 'Manage',
+                'icon'  => 'fas fa-key',
+                'route' => 'api-admin.list'
+            ]
+        ]
+    ]
+];
+
+

The format is generally an array, whereby the first key is the name of your package (api in this case). Thereafter you can specify the main entry, and any sub entries you want to add. The route key should refer to the named route. The sidebar loader will resolve the route itself for you. If you have any permissions requirements for your package, the permission key can be used together with a required SeAT permission to render the view.

+

Character submenus

+

Integrating with the character sub menus is also really easy. Just like the sidebar, all you have to do is create a config file, bootstrap it in the service provider and viola. The namespace should be named package.character.menu in your service provider. A sample config file can be seen below:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
// file: package.character.menu.php
+
+return [
+    [
+        'name'           => 'Research',
+        'permission'     => 'character.research',
+        'highlight_view' => 'research',
+        'route'          => 'character.view.research'
+    ]
+];
+
+

Corporation submenus

+

Integrating with the corporation sub menus is also really easy. Just like the sidebar and character menus, all you have to do is create a config file, bootstrap it in the service provider and viola. The namespace should be named package.corporation.menu in your service provider. A sample config file can be seen below:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
// file: package.corporation.menu.php
+
+return [
+    [
+        'name'           => 'Research',
+        'permission'     => 'corporation.research',
+        'highlight_view' => 'research',
+        'route'          => 'corporation.view.research'
+    ]
+];
+
+

Bootstrapping menu items

+

In the above items, we refer to the files needing to be bootstrapped via the service provider. All this really means is that we have to tell the Laravel application where to find configuration information for a namespace. So, if we wanted to add a sidebar item, we would add the following line to the register() method of the service provider:

+
1
+2
// Include this packages menu items
+$this->mergeConfigFrom(__DIR__ . '/Config/package.sidebar.php', 'package.sidebar');
+
+

The first argument is the file with the sidebar definitions, the second is the namespace.

+

Permissions

+

You are able to register and use your own permissions for use within SeAT. This is relatively simple and done by creating a config file in the location Config/Permissions/package.permissions.php. It should return an array of the following format:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
[
+    'sheet' => [
+        'label'       => 'Grant access to Character Sheet',
+        'description' => 'The Character Sheet contains basic information....',
+        'division'    => 'financial',
+    ],
+    'intel' => [
+        'label'       => 'web::permissions.character_intel_label',
+        'description' => 'web::permissions.character_intel_description',
+        'division'    => 'military',
+    ],
+    'planetary' => [
+        'label'       => 'web::permissions.character_planetary_label',
+        'description' => 'web::permissions.character_planetary_description',
+        'division'    => 'industrial',
+    ],
+];
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
propertymandatorypurpose
labelyesThe displayed name of your permission. It must be a translation token.
descriptionThe displayed permission description. It should help user to determine what the permission is doing. It must be a translation token.
divisionIt will show a "category" icon to help user figures what will be impacted by the permission. Value can be one of military, assets, financial, industrial.
gateIf you need to manage your permission with a custom policy, you can provide a policy FQCN.
+

The definition key (sheet, intel, planetary in the upper sample) will be used as permission unique identifier by the system. This is the one stored in the database, together with scope.

+

Permission Structure

+
+

Info

+

By default, if no gate are provided, those shipped in core will be used according to this pattern :

+
    +
  • character scope: CharacterPolicy, this will require an instance of CharacterInfo to be used in your checks
    • +
  • corporation scope: CorporationPolicy, this will require an instance of CorporationInfo to be used in your checks
    • +
  • anything else: GlobalPolicy
    • +
+

You'll find policy sample at this location.

+

In SeAT 4, a permission is made of a scope and an ability. The ability is defined by the permissions configuration file and the scope is defined on registration.

+
+

This config file is then loaded from your app service provider as below:

+
 $this->registerPermissions(__DIR__ . '/Config/Permissions/package.permissions.php', 'package');
+
+

Database

+

For our API package, we have a database requirement. We need to store api tokens and the ip address that is allowed to use them. We are also going to store an access log (based on the config setting). We create migrations and models just like you would for a base Laravel 6 application. The only thing to remember is that your migrations for your package must be published (and specified in your service provider).

+

Registering these migrations looks like the following:

+
$this->loadMigrationsFrom(__DIR__ . '/database/migrations/');
+
+

Releasing the plugin

+

The usual setup is to host the code on github and distribute the code via packagist. +When you submit your plugin on packagist, it will be installable like the other plugins by adding <vendor>/<package> to the appropriate section of your .env file.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/seat_api/index.html b/developer_guides/seat_api/index.html new file mode 100644 index 00000000..37db0e42 --- /dev/null +++ b/developer_guides/seat_api/index.html @@ -0,0 +1,1467 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + SeAT API - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Introduction

+

SeAT has a REST API. Endpoints are protected by an access token that is limited by IP address. For every IP address that wants to make API requests to SeAT, a unique token is required. API Tokens have no concept of ACL's. The API should primarily be used for integrations with other systems.

+

Definitions

+

Currently, all API endpoints live at <seat url>/api/<version> where <seat url> is the full url to your SeAT instance and <version> is the API version you wish to interact with.

+

Since SeAT 3.0, API documentation is generated from source code annotations and presented via a Swagger UI. As a result, endpoint documentation is now directly available on your instance at the following address <seat url>/api/documentation. A link to the documentation is also provided on the API key management page available to users with the Superuser role.

+
+

Swagger JSON

+

If you get an error when viewing the API documentation that complains about a file called api-docs.json, make sure that you ran the php artisan l5-swagger:generate command as part of the installation and upgrade routines.

+
+

Authentication

+

Authentication to the SeAT API is done via a X-Token header. A token may be obtained by browsing to the API settings page in the SeAT WebUI and generating one. A sample request using curl with an authentication token can be seen below:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
$ curl -X GET -H "X-Token:123456" -H "Accept: application/json" http://localhost:8000/api/v1/key
+*   Trying ::1...
+* Connected to localhost (::1) port 8000 (#0)
+> GET /api/v1/key HTTP/1.1
+> Host: localhost:8000
+> User-Agent: curl/7.43.0
+> Accept: application/json
+> X-Token:123456
+>
+< HTTP/1.1 200 OK
+< Host: localhost:8000
+< Connection: close
+< Cache-Control: no-cache
+< Date: Sat, 28 Nov 2015 22:27:12 GMT
+< Content-Type: application/json
+
+

Content-Type

+

Make sure you specify the Accepted content-type header as application/json. When using cURL, you can specify it with -H

+

Example:

+
1
+2
$ curl -X POST https://seat.testsite.local/api/v1/key -H "Accept: application/json" -H "X-Token: L3SxgdX4XUw6pVWVSCftgsh16eAbBF3D" -d "key_id=123&v_code=123"
+{"v_code":["The v code must be 64 characters."]}
+
+

If you don't do this, the API will respond with a redirect and not give you the expected content.

+

Errors

+

All SeAT API responses will include the appropriate HTTP response codes. You should check this for error handling purposes. Some sample response codes could be:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeStatusDescription
200OKThe request was successful.
404Not FoundThe requested endpoint could not be found.
422Unprocessable EntityTypically, input validation has failed. The response json should contain the errors.
500Internal Server ErrorSomething bad has happened. Check the server and Laravel log files for more details.
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/developer_guides/updating_plugins/index.html b/developer_guides/updating_plugins/index.html new file mode 100644 index 00000000..23a8ccc8 --- /dev/null +++ b/developer_guides/updating_plugins/index.html @@ -0,0 +1,1442 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Updating Plugins - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Updating Plugins

+

This page aims to help with porting a SeAT plugin to a newer version of seat.

+

From SeAT 4

+

SeAT 5 mainly upgrades the php and laravel version as well as all dependencies to their newest version. However, there are a few other breaking changes that can't be ignored.

+
    +
  • PHP 8.2: SeAT now runs on php 8.2, enabling new features like enums and better type hinting, but also breaking a few things.
    • +
  • Route Prefixing: All routes from the seat core start with seatcore::. For example, notifications.integrations.list turns into seatcore::notifications.integrations.list. If your plugin uses routes pointing to the seat core, you will have to update them.
    • +
  • Notifications: All notifications from SeAT 4 continue to work, but by updating them you can unlock more features like discord pings. See the notifications guide for more details.
    • +
  • The Seat\Eveapi\Jobs\Middleware\WithoutOverlapping job middleware backport is now provided by laravel and got removed from the SeAT core. Use Illuminate\Queue\Middleware\WithoutOverlapping instead. Just swapping the import should be enough, as they are compatible.
    • +
  • Some, but not all ways of exporting data from DataTables are broken. Just check whether they work and fix if required.
    • +
  • There are a few minor breaking changes between Laravel 6 and 10:
    • +
  • MyJob::dispatchNow() got replaced with MyJob::dispatchSync()
    • +
  • For a full list, head over to the laravel documentation.
    • +
+

From SeAT 3

+

If you're upgrading a SeAT 3.x plugin, the cheat sheet bellow will probably helps you.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SeAT 3.xSeAT 4.xPurpose
auth()->user()auth()->user()Retrieve the currently authenticated user.
auth()->user()->group->main_characterauth()->user()->main_characterRetrieve the main character from the currently authenticated user.
auth()->user()->group->main_character->nameauth()->user()->nameRetrieve the main character name from the currently authenticated user.
auth()->user()->group->charactersauth()->user()->charactersRetrieve all characters from the currently authenticated user.
auth()->user()->refresh_tokenCharacterInfo()->refresh_tokenRetrieve the refresh token attached to a character.
auth()->user()->group->refresh_tokensauth()->user()->refresh_tokensRetrieve all refresh tokens attached to authenticated user.
+

Also, if you need it, a table called mig_groups is available in database containing a list of all converted group into standalone user. +This table will stay here until next SeAT major update.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldPurpose
group_idThe unique ID from SeAT 3 user group
old_user_idThe unique ID from SeAT 3 user (match to Character ID)
new_user_idThe unique ID from SeAT 4 user
main_character_idThe SeAT 3 registered main character ID - or random from the User Group if none were set
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/img/authorization.png b/img/authorization.png new file mode 100644 index 00000000..a18cfea8 Binary files /dev/null and b/img/authorization.png differ diff --git a/img/authorization_members.png b/img/authorization_members.png new file mode 100644 index 00000000..ad81a6a9 Binary files /dev/null and b/img/authorization_members.png differ diff --git a/img/authorization_permissions.png b/img/authorization_permissions.png new file mode 100644 index 00000000..30d56a3c Binary files /dev/null and b/img/authorization_permissions.png differ diff --git a/img/customized-signin-page.png b/img/customized-signin-page.png new file mode 100644 index 00000000..7272c49d Binary files /dev/null and b/img/customized-signin-page.png differ diff --git a/img/moons_reporter.png b/img/moons_reporter.png new file mode 100644 index 00000000..5ec3284b Binary files /dev/null and b/img/moons_reporter.png differ diff --git a/img/moons_reporter_details.png b/img/moons_reporter_details.png new file mode 100644 index 00000000..49684989 Binary files /dev/null and b/img/moons_reporter_details.png differ diff --git a/img/moons_reporter_import.png b/img/moons_reporter_import.png new file mode 100644 index 00000000..92399e86 Binary files /dev/null and b/img/moons_reporter_import.png differ diff --git a/img/moons_reporter_search.png b/img/moons_reporter_search.png new file mode 100644 index 00000000..33e05857 Binary files /dev/null and b/img/moons_reporter_search.png differ diff --git a/img/permissions_structure.png b/img/permissions_structure.png new file mode 100644 index 00000000..117932cf Binary files /dev/null and b/img/permissions_structure.png differ diff --git a/img/seat_jobs_flow.drawio b/img/seat_jobs_flow.drawio new file mode 100644 index 00000000..698d3b0f --- /dev/null +++ b/img/seat_jobs_flow.drawio @@ -0,0 +1 @@ +7V1bj+I2FP41SNuHGeWe8DgXphdtpdVO1Xb7UpnEgLshZh0zMP31tXMh8SVDYAkhdFYrDXYck5zz+fPxOcdmZD8stz8SsFr8iiMYjywj2o7sx5FlmY5ljfh/I3rNa3zPzivmBEVFo6riGf0Li0qjqF2jCKZCQ4pxTNFKrAxxksCQCnWAELwRm81wLH7rCsyhUvEcglit/QNFdJHXBpZf1f8E0XxRfrPpjfMrS1A2Lt4kXYAIb2pV9mRkPxCMaf5puX2AMRdeKZf8vqeGq7sHIzChbW74a/tl9vfmyXn46ppWMCW///Lt8cZz8m5eQLwu3nhkeTHr8D5CL+zjnH+cPP/M2kxBCiP29x88TctG7Otq7YoXpa+l9AheJxHkD2Cwy5sFovB5BUJ+dcPwwuoWdBmzksk+xmAK43sQfp1ntz3gGBN2KcEJa38/wwkt4GF6rAxiNE9YIWSvDwlvgOK4vGdk2ZELg8hh9Skl+CuUepvHIE2Lx8LsiRDl+LR5cU5AhFintb7GfmT4Prv2AglFDBx3xZdTzN8h5R0k8994IX+47GELMZhFWejvMe+vED7rFW4b1WruwMJGGcRLSMkra1LcMC7g9SoWNxVYbbsA66IOVMMvWoJihMx3XVcgYh8KHB2CKfttTNUA4n1bc/hn8rlJM+3esQamt9pm0imv88csRF5VxnBG601yDP6ByVdI+gCohD8Ag1nYhL/ybbJ3UPDhT+68idGAo/ogKJD3Meslr/oeSBUYsh0VREFJY3UQBZ1ByFIg9EvGOmdT32wGvfAQ9b2lJkm9T0+BYRidqc9yNeozx6r6xl2pTzepSJqDEZtmiyImdIHnOAHxpKq9F3VbtfmIc55llf9ASl8LQYM1xaK+4RbRP/ntt25R+lK78rgtes4Kr7XCJ0gQkwOfVLK6/Nn5A7+tEPZ+eE1C+IZgGhRHYAwoehH712mluPUTRuybd1OA45vCHFCaIGUP+WMVN9UthD39mKbUEQVkDqnSUYaR3escDxuzjS3CeCBDEiawieOVez58hhFKf2g5J+QjvrT2LBFUzIpb8XbL7ZwbvLezGG/CBSD0NgIUcBOpgYhk02GKKcXL09gAjmmLRoAy/pldqo5/r6vxb+o02QMBJOxlagzAi1/Kgc4LFQdkpdd66XgWyEfJG+LxO2EB1/DE0es6rWjgZKNXnbP7VnogaP3WMP2eNW8aV6l6R7X4Gd+uAA0XWgh85JaYqDZlOSfz5RJFUY4QyBYKYJr1x9Wz4m+Vvad7P3If32LUwklQ3DzaLc3rqnwD2438e8Ow5vnFKutYXZZN8GyWwm5GqG5h9r+h5b3GmdVyELvfOYa/b2q9ENt64Dr0+tSho+rwyujS2UeXljEWZqwb++LJ072+gVeukMs18Zeq375WyG0HcNCJIaWsgIN2S+mTgcy7CJD1oM9xn4SsW7koToQ87GFgEi5gSgmgmLR3QPyECfoXJzsXxJTIrfc4JUp+z+aCTzhFFGHBjaAPTbTyXHC/ZJN3NHOF8n8n8lSUsQjZxVTzVfgaT3NnwQqV1blMQEizGMJpPEPLdUzRTYTD9TITk9Y/dALhmmYgCHfnCKw7ggNVuJ35gVQ2CzFZYTZ2GHgHJ16rhXhNQwPezuTrK/JdsG8dmlw9yXvZO2wDRawJpmjG2HWQuJW9Q73Ld6zId7WexigcmmBt+8KAWybN1BeWcAaYOIYmWt+6NNGqXLvJMg0UyVbWt9kgn/o6fprieE3hHQnLgDGvrUpVBktdVx0YC7bnKRIeayYzpzMJq7Q7bAnL9oJOwlp7oTsRq8w7bBHbtrtXxIF7RglbKgMPW8Ky8aCVsCa/rDsJq7HlYUtYNn97J2JLdYcMW8KyMdG7hG0Vw+uVIt2BOfqKoMZeT5/Va/zMUmMveXbzMwV0zR18I/tJUcWxKUEwRGnmp+vO5SNC27GDdjbGrvL04FbpI8FDB7fbFty9BhYt1ZuZg/szoJD9+YiWiEc7PkMQLrJc/mGB3RDB7vquCnZdnnJ3YHdViQ+fyb2WYHcbwrxnArvqXZ78PuFMDskLN1auhNJ9s3dKd5smzQkhPAo2bAEH5ev1J2BL9S7dM0YIOWnnCc8fJil6xJtksg3hiruhfziVwCkkS5Rk4czuQidSXN1xNZguDYez+PMs1dukkTifN7NJc6Bi96QJc6yZMJ1zulEt1QOlCZeLmmgbY5+8wJz65XFyZMj9khXr+rei58vXGf6uZtNPZ6q1VQ5TDaEkuuObclkp5DswUShK9VQJSVWW1EjIAN+lTPWVnth6kdywR6CmXVczQ5V135kGZTsSbxiB2EXbHUX2WFqeulJHHe8ocjQBMUYOKi6HmGVpN2CklpQuCL/cX3W5OZa2Oim/U8jRroiGFMl3CjmMQlRf7StUc0CGySANEKkYxPECMWFvACSiMzHfSeQ4F4/VkJc7MBKxfHG7ge+dmUSsa7ZDGjBSsQjjcFH+F08ijrqYWREcwlTD/C25RDyGwLgNgoPp5IQMUKaK7WcAq08GcCQPhtNyQ4a6RVYJlJ33bANHNW2vC1B+Wzw1eDbe8XQYnjRJtFeFp6Atnhq21L/j6bAQj+opuQA8Hbvb8YQ4HLfEodmrpew4Yq7p0Th0xlJH58ahuty+AByeEE9tV15mr+6b68GTuvK6Ljy1dQeavUYUrgdPmqyTLBXiEVCgQKqMEjLFgjiGMZ4TsJQCiUqUcVUDi3BjDUXawKKYjlvLrOW95qdrMrha9uhcu33lTIvxuBiNve2YdNV1fa444zk/Uc74sAQEgWh6skD/nnPh3j6VsstT40wpLdrcqaKe26/jhHFX2tHFf1plB+wL7n/4DL+tYUqfAIph1EM2x3kGnOWK7Bj4mtQm95wJH666TtWGT/7nDvkyBW1/zmWvZqElOeRNwzpyHreksN7YP+887qnrXV2W+lEm4eFHzF7AOrc9AhtS3M8UErJlBJZnRR8cWA7knkypp64hqC51UZIy+md1I5/1aaxXUZ64nxcjGMOsmFJWzTdgn2oRswexF3rYm9s6Ub3fbCqzyc46GLKeDFlX6qlryLY5n2oPAvccjr47+/6akGq2jo40bKk4D1LLoGAZbrePxKkn9uPIvxNwNEpZsfrBlLx59bMz9uQ/ \ No newline at end of file diff --git a/img/seat_jobs_flow.png b/img/seat_jobs_flow.png new file mode 100644 index 00000000..1e70fac7 Binary files /dev/null and b/img/seat_jobs_flow.png differ diff --git a/img/squads_card_applications.png b/img/squads_card_applications.png new file mode 100644 index 00000000..7273d3f2 Binary files /dev/null and b/img/squads_card_applications.png differ diff --git a/img/squads_card_general.png b/img/squads_card_general.png new file mode 100644 index 00000000..52e9fe91 Binary files /dev/null and b/img/squads_card_general.png differ diff --git a/img/squads_card_members.png b/img/squads_card_members.png new file mode 100644 index 00000000..b92baae5 Binary files /dev/null and b/img/squads_card_members.png differ diff --git a/img/squads_card_roles.png b/img/squads_card_roles.png new file mode 100644 index 00000000..33b4c422 Binary files /dev/null and b/img/squads_card_roles.png differ diff --git a/img/squads_create.png b/img/squads_create.png new file mode 100644 index 00000000..8cc10742 Binary files /dev/null and b/img/squads_create.png differ diff --git a/img/squads_filters.png b/img/squads_filters.png new file mode 100644 index 00000000..2b6d8908 Binary files /dev/null and b/img/squads_filters.png differ diff --git a/img/squads_list.png b/img/squads_list.png new file mode 100644 index 00000000..13dbbf82 Binary files /dev/null and b/img/squads_list.png differ diff --git a/img/squads_sidebar.png b/img/squads_sidebar.png new file mode 100644 index 00000000..83804662 Binary files /dev/null and b/img/squads_sidebar.png differ diff --git a/img/squads_tile.png b/img/squads_tile.png new file mode 100644 index 00000000..8b73d19c Binary files /dev/null and b/img/squads_tile.png differ diff --git a/index.html b/index.html new file mode 100644 index 00000000..66b696bf --- /dev/null +++ b/index.html @@ -0,0 +1,1434 @@ + + + + + + + + + + + + + + + + + + + + + + + + SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Home

+

Welcome to the SeAT documentation pages!

+

This site aims to provide you with useful, technical information about SeAT. Please refer to the index on the side for detailed installation instructions, documentation about SeAT internals and/or development guidelines!

+
+

Contributing to Documentation

+

Great software is coupled with even greater documentation. If you would like to contribute to making this documentation even better, please don't hesitate to fork the documentation repository and submit a pull request with your contribution. We are always looking for better information.

+
+

Quick Start

+

There are many ways to install SeAT. In all cases you will need a dedicated server as a minimum. +Using the docker installation you are free to choose any Docker capable host (yes, even Windows!). +However, if you choose to install SeAT on bare metal, you'll need a linux distribution. +We suggest you choose an LTS version of Ubuntu, Debian or CentOS.

+

Installation Options

+

Ignoring the details, to get SeAT installed quickly you have a few options. +All of them will get you SeAT installed, but you still have to manually configure an SSO application on the EVE Online Developers Portal.

+ + + + + + + + + + + + + + + + + +
MethodComments
DockerFollow our docker installation guide. This is the recommended way to install SeAT as it will handle near everything for you.
ManuallyYou can always install SeAT by following our manual installation guide. All you need is PHP, MariaDB, Redis and a web server and some Linux experience.
+
+

Warning

+

While installing SeAT - choose one method, and stick to it. Otherwise, you'll get SeAT installed multiple times.

+
+

Upgrades / Updates

+

SeAT is being worked on continuously. New features are added, performance improvements are made and bugs are fixed. If you wish to upgrade to the latest version of SeAT refer to the upgrade section.

+

Contact

+

Want to get in touch with developers, or just other users of SeAT? Refer to the contact section to find out how!

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/installation/docker_installation/index.html b/installation/docker_installation/index.html new file mode 100644 index 00000000..9b23e54d --- /dev/null +++ b/installation/docker_installation/index.html @@ -0,0 +1,1728 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Docker Installation (5.x) - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Docker

+

Docker is ideally the installation route you want to go. Docker enables us to run SeAT on any platform capable of running docker itself (which includes Windows!). Additionally, upgrades and service maintenance are really low effort as you don't have to care about any dependencies. All of it is maintained within a docker stack, DockerHub and the GitHub Container Registry.

+
+

Windows owner recommendation

+

If you plan on running Docker on Windows, for the best performance it is suggested that you run Docker using the Windows Subsystem for Linux 2 (WSL2) backend, available starting in Windows 10/Windows Server 20H1 (build 2004) releases.

+
+
+

Windows owner special installation path

+

If you are using Docker on Windows, you will need to use the Manual Deployment option below.

+
+
+

Tip

+

Before starting the installation process, be sure you read this complete document first. It will help you understand all the steps from an installation process.

+

If you feel like docker might not be your cup of tea, checkout some of the other getting started guides that are available.

+
+
+

Eve Application and ESI

+

SeAT uses CCP's ESI service in order to retrieve EVE Online-related information. Before you can make any authenticated calls to ESI, you have to register a third-party EVE application on the developers portal. This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

+
+

Internal Container Setup Overview

+

The setup for SeAT's docker installation orchestrated using docker-compose. With docker-compose, we can use YAML files to define the entire stack complete with all the dependencies required to run SeAT. A pre-built and recommended compose file (which is also used by the bootstrapping script) is hosted in the seat-docker repository here.

+

The official SeAT repository for Docker is shipped with a total of 4 YAML files, allowing you both flexibility and understandability of the overall stack. A high-level overview of its contents is:

+
    +
  • A main docker-compose.yml file in which are listed SeAT services (front to serve web ui, worker to process jobs, scheduler to manage repetitive tasks and cache to store jobs queue)
    • +
  • A database docker-compose.mariadb.yml file in which is listed a mariadb service - this way, you can replace mariadb by another supported database engine
    • +
  • A Traefik docker-compose.traefik.yml file in which is listed a traefik service - this way you can simply and safely server your SeAT frontend to the rest of the world
    • +
  • An alternative to Traefik docker-compose.proxy.yml file in which is adapted front SeAT container to be server behind a reverse proxy of your choice
    • +
  • A volume called mariadb-data and seat-storage is defined. These are the most important volumes as they contain all SeAT data. You should configure a backup solution for them!
    • +
  • The environment is configured using a top-level .env file.
    • +
  • Only one port is exposed by default. This is tcp/8080. It can be connected to in order to access the SeAT web interface.
    • +
  • When using the stack with Traefik (which is the easier and recommended approach), ports tcp/80 and tcp/443 are exposed and tcp/8080 remain unbound.
    • +
  • All containers are configured to restart on failure, so if your server reboots or a container dies for whatever reason it should automatically start up again.
    • +
+

The table bellow is listed overall consumed Docker image, including SeAT custom one - together with their source repository.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Image NameImage Repository
mariadb:10.11https://hub.docker.com/_/mariadb/
redis:5-alpinehttps://hub.docker.com/_/redis/
traefik:2.10https://hub.docker.com/_/traefik
ghcr.io/eveseat/seat:5https://github.com/eveseat/seat-docker/pkgs/container/seat
+

SeAT Docker Installation

+

Depending on whether you already have docker and docker compose already installed, you may choose how to start the installation. If you already have the required tooling installed and running their latest versions, all you need to do is download the latest SeAT Docker template archive to get started.

+

Automated Setup Script

+

If you do not have the required software installed yet, consider running the bootstrap script that will check for docker and docker compose, install it and start the SeAT stack up for you. The script can be run with:

+
bash <(curl -fsSL https://raw.githubusercontent.com/eveseat/seat-docker/master/bootstrap.sh)
+
+

Once the script is finished, you can skip to the monitoring the stack section of this guide.

+

If you don't want to run this script, follow along in the next section of this guide.

+

Manual Deployment

+

Docker Download

+

If you do not have docker, install it now.

+
+
+
+

Under Linux, you can achieve this action by using the following command as root:

+
sh <(curl -fsSL get.docker.com)
+
+
+
+

Under Windows, you can achieve this action by downloading and installing Docker Desktop.

+
+
+
+

Docker-compose Download

+

If you do not have docker compose, install it now with the following command as root (Docker Compose is included with Docker Desktop on Windows):

+
1
+2
+3
# Downloads and install docker compose from Docker repository
+sudo apt-get update
+sudo apt-get install docker-compose-plugin
+
+

Docker compose working directory

+

With docker and docker compose ready, create yourself a directory in /opt with mkdir -p /opt/seat-docker and cd to it. Remember this directory as you will need to come back to it often.

+

On Windows, create the C:\seat-docker directory with mkdir C:\seat-docker and cd to it.

+

SeAT docker-compose.yml and .env File

+

Then, download the SeAT Docker template archive with:

+
+
+
+
curl -fsSL https://github.com/eveseat/seat-docker/archive/refs/heads/master.zip -o seat-docker.zip
+
+
+
+
Invoke-WebRequest -Uri https://github.com/eveseat/seat-docker/archive/refs/heads/master.zip -OutFile seat-docker.zip
+
+
+
+
+

Next, decompress the template archive:

+
+
+
+
unzip seat-docker.zip -d /opt/seat-docker -j
+
+
+
+
Expand-Archive -Path c:\seat-docker\seat-docker.zip -DestinationPath c:\seat-docker
+
+
+
+
+

Next, we will generate a unique application key - this is used internally for encryption:

+
+
+
+
sed -i -- 's/APP_KEY=insecure/APP_KEY='$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c32 ; echo '')'/g' .env
+
+
+
+
$appkey = (-join ((65..90) + (97..122) | Get-Random -Count 32 | % {[char]$_})); (Get-Content .env -Raw) -replace "APP_KEY=insecure", "APP_KEY=$appkey" | Set-Content .env
+
+
+
+
+

SeAT docker configuration

+

Open up the .env file in a text editor and fill in a few of the configuration items needed.

+
    +
  • PROXY_BACKEND_HTTP_PORT adapt to any integer of your convenience between 1 and 65535 in case you plan to serve SeAT behind a reverse proxy.
    • +
  • TRAEFIK_ACME_EMAIL adapt with your own e-mail address in case you plan to serve SeAT behind Traefik.
    • +
  • SEAT_DOMAIN should be set to the domain your installation lives on and on which SeAT UI will be served.
    • +
  • DB_PASSWORD must be adapt with a strong password of your own - it will be used as SeAT credential for its database.
    • +
+
+

Warning

+

The DB_PASSWORD value have to and must be changed only once - before any start of the overall stack. +As soon as the database container is created, SeAT user account is initialized with the DB_PASSWORD value. +Changing it after the initial startup will prevent the stack to boot.

+

Also, at the initial startup, the root password from the database container will be shown in logs. +You should consider taking a note of it - otherwise you will no longer have a way to recovery of a critical outage (ie: misconfiguration, etc...)

+
+

Finally, in case you plan to serve SeAT using Traefik, create an ACME configuration file with:

+
1
+2
+3
mkdir acme
+touch acme/acme.json
+chmod 600 acme/acme.json
+
+
+

Info

+

SeAT docker template is shipped with Traefik to hide your container behind a proxy and securing traffic up to it. In case you want to manage traffic proxying and certification on your own, you must use docker-compose.proxy.yml file on startup.

+
+
+

Warning

+

The location of the docker-compose.yml and .env files are important. You need to cd back to the directory where these are stored in order to be able to execute commands for this stack at a later stage.

+

Also, be sure you provide a valid e-mail address as it will be used to register your account against Let's Encrypt in case you plan to serve SeAT with Traefik. For those unfamiliar with this, it's CA that provides valid certificates for free.

+
+

ESI Configuration

+

As mentioned at the start of the guide, it is necessary for you to configure ESI. For instructions on how to do this, please refer to the ESI Setup Guide.

+

With the configuration files ready, start up the stack with:

+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up
+
+
+
+
+

Monitoring the Stack

+

Knowing what is going on inside your containers is crucial to understanding how everything is running as well as useful when debugging any problems that may occur. While the containers are starting up or have been running for a while, you can always cd to the directory where your docker-compose.yml file lives and run the logs command to see the output of all the containers in the stack. For example:

+
1
+2
cd /opt/seat-docker
+docker compose logs --tail 10 -f
+
+

These commands will cd to the directory containing the stacks docker-compose.yml file and run the logs command, showing the last 10 log entries and then printing new ones as they arrive. If you leave away the --tail 10part, you can view all logs since the container startup.

+

Configuration Changes

+

All the relevant configuration lives inside the .env file, next to your docker-compose.yml file. Modify their values by opening it in a text editor, making the appropriate changes, and saving it again. +Once that is done, restart the container environment:

+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+
+

Success

+

You made it! Use a browser and browse to the domain / subdomain of your server to access SeAT!

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/installation/manual_installation/index.html b/installation/manual_installation/index.html new file mode 100644 index 00000000..2984f629 --- /dev/null +++ b/installation/manual_installation/index.html @@ -0,0 +1,2194 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Manual Installation (5.x) - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Manual Installation

+

This guide attempts to explain how to manually install SeAT onto an Ubuntu Server. +A small amount of Linux experience is preferred when it comes to this guide, although it is not entirely mandatory.

+
+

Info

+

This guide has been written targetting Ubuntu. However, you can use it to deploy SeAT on any linux distribution. +Just be sure you adapt commands to targetted distribution (mostly those related to the package manager).

+
+
+

Hint

+

Before starting to do anything, be sure you read the complete workflow once. +It will help you to understand all steps from the installation process.

+
+
+

Eve Application and ESI

+

SeAT consumes CCP's ESI service in order to retrieve EVE Online related information. +Before you can make any authenticated calls to ESI, you have to register a third party EVE application on the developers portal. +This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

+
+

Getting started

+

We are going to assume you have root access to a fresh Ubuntu Server. +Typically access is gained via SSH. +All of the below commands are to be entered in the SSH terminal session for the installation & configuration of SeAT. +If the server you want to install SeAT on is being used for other things too (such as hosting MySQL databases and or websites), then please keep that in mind while following this guide.

+

Packages are installed using the aptitude package manager as the root user.

+

OS Installation

+

Operating System

+

Before we get to installing SeAT, lets ensure that your operating system is up to date. We can do that with basics :

+
    +
  • apt-get update to refresh the repositories cache.
    • +
  • apt-get full-upgrade to update any installed packages.
    • +
  • reboot in order to ensure any updated software is the current running version.
    • +
  • apt-get autoremove (after the reboot) to cleanup any unneeded packages.
    • +
+

Database

+

SeAT relies heavily on a database to function. Everything it learns is stored here, along with things such as user accounts for your users. +It comes without saying that database security is a very important aspect too. So, ensure that you choose very strong passwords for your installation where required.

+

SeAT officially supports just MariaDB. Using MySQL or PostreSQL might appear to work on the surface, however it is likely that you will run into issues due to differences between the databases later down the line, and almost no testing with them is done during development.

+

We need to ensure that we have the latest MariaDB installed. To help with this, MariaDB provides an official repository to get the latest versions.

+

To download and install the repo, you need curl. Install it with:

+
apt-get install curl
+
+

Let's add this repository with:

+
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | bash
+
+

With the repository now setup, lets install the database server:

+
+

Warning

During the installation, you may be asked to set a password for the root MariaDB user account. +Make sure you set a long, strong password and remember it. It will be needed for the next step.

+

+
+
apt-get install mariadb-server
+
+

Before we can configure the database, we have to start it:

+
systemctl enable mariadb.service
+
+

Next, we are going to secure the database server by removing anonymous access and setting a root password (if you have not been prompted for it yet).

+
+

Note

+

The database root password should not be confused with the operating systems root passwords. They are both completely different. +They should also not have the same password.

+
+

To secure the database, run:

+
mariadb-secure-installation
+
+

This will ask you a series of questions where you should generally just answer yes to. If you already set a root password in the previous step then you dont have to set it again, otherwise, make sure you choose a long, strong password for the root account. An example run is shown below:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
[...]
+
+Enter current password for root (enter for none):  IF ONE WAS SET, IGNORE THIS
+OK, successfully used password, moving on...
+
+[...]
+
+Set root password? [Y/n] y
+New password:             SET A STRONG PASSWORD HERE
+Re-enter new password:    SET A STRONG PASSWORD HERE
+Password updated successfully!
+Reloading privilege tables..
+ ... Success!
+
+[...]
+
+Remove anonymous users? [Y/n] y
+ ... Success!
+
+[...]
+
+Disallow root login remotely? [Y/n] y
+ ... Success!
+
+[...]
+
+Remove test database and access to it? [Y/n] y
+
+[...]
+
+Reload privilege tables now? [Y/n] y
+ ... Success!
+
+[...]
+
+

That concludes the installation of the database server and securing it.

+

Next, we need to create an actual user and database for SeAT to use on the newly installed server. To do this we use the mariadb command line client and enter a few commands as the root user to create the database and the user that will be accessing the server. Let get to it.

+

Fire up the mariadb client as root by running:

+
mariadb -uroot -p
+
+

This will prompt you for a password. Use the password you configured for the root account when we ran mysql_secure_installation. This will most probably be the last time you need to use this password :)

+

If the password was correct, you should see a prompt similar to the one below:

+
1
+2
+3
+4
+5
+6
+7
+8
+9
root@ubuntu:~# mysql -uroot -p
+Enter password:
+Welcome to the MariaDB monitor.  Commands end with ; or \g.
+Your MariaDB connection id is 16
+Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+MariaDB [(none)]>
+
+

Create a new database for SeAT to use with:

+
create database seat;
+
+

The output should be similar to the below:

+
1
+2
MariaDB [(none)]> create database seat;
+Query OK, 1 row affected (0.00 sec)
+
+

Next, we need to create the user that SeAT itself will use to connect and use the new seat database:

+
GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';
+
+

Of course, you need to replace s_p3rs3c3r3tp455w0rd with your own unique and strong password. +Successfully running this should present you with output similar to the below:

+
1
+2
MariaDB [(none)]> GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';
+Query OK, 0 rows affected (0.00 sec)
+
+

In the example above, we have effectively declared that SeAT will be using the database as seat:s_p3rs3c3r3tp455w0rd@localhost/seat.

+

Finally, we will flush the database server privileges:

+
FLUSH PRIVILEGES;
+
+

That concludes the database server setup. You can exit the prompt with exit;

+
+

Note

+

Remember the password for the seat database user as we will need it later to configure SeAT.

+
+

PHP

+

Since SeAT is written primarily in PHP, we will need to install PHP packages. Ubuntu based systems can make use of the ondrej PPA which is a very popular repository used for specific PHP versions.

+

Depending on the version of Ubuntu you are using, a release specific repository URL should be used for the PPA. Select the tab applicable to your Ubuntu version and run the commands within.

+
+
+
+
1
+2
echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu jammy main" >> /etc/apt/sources.list.d/php.list
+echo "deb-src http://ppa.launchpad.net/ondrej/php/ubuntu jammy main" >> /etc/apt/sources.list.d/php.list
+
+
+
+
1
+2
echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu focal main" >> /etc/apt/sources.list.d/php.list
+echo "deb-src http://ppa.launchpad.net/ondrej/php/ubuntu focal main" >> /etc/apt/sources.list.d/php.list
+
+
+
+
1
+2
echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu bionic main" >> /etc/apt/sources.list.d/php.list
+echo "deb-src http://ppa.launchpad.net/ondrej/php/ubuntu bionic main" >> /etc/apt/sources.list.d/php.list
+
+
+
+
+

Next, we will have to download the new repositories GPG signing key and add it into our keychain

+
apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 4F4EA0AAE5267A6C
+
+

With the new repository configured, update the package lists with:

+
apt-get update
+
+

Finally, install the required PHP packages with:

+
1
+2
apt-get install libpng-dev libfreetype6-dev libjpeg-dev
+apt-get install openssl zip php8.2-bz2 php8.2-cli php8.2-curl php8.2-dom php8.2-gd php8.2-gmp php8.2-intl php8.2-mbstring php8.2-mysql php8.2-opcache php8.2-redis php8.2-zip
+
+

Redis

+

SeAT makes use of Redis as a cache and message broker for the Queue back end. Installing it is really easy. Do it with:

+
apt-get install redis-server
+
+
+

Hint

+

By default, redis is making backup from its database - so it ensure integrity in case of failure. +However, in certain condition, like power outage, this backup might be unprocessable and avoid redis to run.

+

Since we don't store anything critical in it, you may want to disable this. To do so, edit the configuration file +using nano /etc/redis/redis.conf and search line appendonly no, change it for appendonly yes

+

If you are on a small server, You may also want to limit the part of memory used by redis (by default, it will consume all available memory). +To do so, into the redis configuration file, search line # maxmemory <bytes> and change it for maxmemory xGB where x is the memory limit you want to set.

+
+

You might also need to start redis: +

systemctl enable redis-server.service
+

+

SeAT Installation

+

Prerequisites

+

Excellent progress! All of the operating system level requirements are now met and we are almost ready to install SeAT itself. The only thing that is outstanding is the package manager called composer as well as the git client. The combination of composer and git will let us download the SeAT source code from Github and install it locally.

+

Git

+

Install git with:

+
apt-get install git
+
+

Composer

+

Next, install composer with:

+
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && hash -r
+
+

Thats it. Lets install SeAT! By default, we suggest you run SeAT from within /var/www/seat. As part of the installation, the seat directory will be created for us, but we will need to create /var/www for now as we have not yet configured the web server.

+

Create the www directory with:

+
mkdir -p /var/www
+
+

Next, cd to the new /var/www directory with:

+
cd /var/www
+
+

SeAT Download

+

With all of the prerequisites installed as well as our www directory ready we can finally download SeAT. Do that with:

+
composer create-project eveseat/seat:5.0 --no-dev --no-interaction
+
+

Once the download is done, you should have seen output such as:

+
Writing lock file
+Generating optimized autoload files
+> Illuminate\Foundation\ComposerScripts::postAutoloadDump
+> @php artisan package:discover
+Discovered Package: darkaonline/l5-swagger
+Discovered Package: eveseat/api
+Discovered Package: eveseat/console
+Discovered Package: eveseat/eveapi
+Discovered Package: eveseat/notifications
+Discovered Package: eveseat/services
+Discovered Package: eveseat/web
+Package manifest generated successfully.
+> @php artisan key:generate
+Application key [base64:CmhqYNkaIcHo8nYC8LiEWa3U5/+BiTLih5dZftxlV2k=] set successfully.
+
+

Permissions

+

You may have noticed a warning about composer running as root. For now this can be safely ignored. Post the installation of the SeAT source code, we need to fix up the permissions of the downloaded files. Do that with:

+
1
+2
chown -R www-data:www-data /var/www/seat
+chmod -R guo+w /var/www/seat/storage/
+
+

This will ensure that the web server, cron jobs and workers have access to the source code as well as logs.

+

SeAT Setup

+

With SeAT downloaded, we need to configure it. There are a number of configuration tasks needed. These include editing the applications .env file as well as running some commands that setup and seed the database. A configuration value reference can be found here.

+

.env setup

+

The first task would be to configure the applications database connection. Open the file located at /var/www/seat/.env with something like vi or nano and update the database options with your values. Typically, only the password would really need to be updated. If you are making use of an existing database somewhere else over the network, update the applicable fields such as DB_HOST accordingly.

+
1
+2
+3
+4
+5
+6
+7
DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=seat
+DB_USERNAME=seat
+DB_PASSWORD=s_p3rs3c3r3tp455w0rd # <-- this is the value you probably need to edit.
+DB_DEBUG=false
+
+

Database Migrations and Seeds

+

Next we need to publish the database migrations and web assets (such as JavaScript scripts and CSS Style sheets), run those migrations and finally seed the SeAT job schedule.

+

Publish the assets and database migrations with:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'
+
+

Run the database migrations with:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'
+
+

Seed the SeAT schedule with:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\Services\\Database\\Seeders\\PluginDatabaseSeeder'
+
+

EVE Sde Update

+

SeAT makes use of a number of tables from the EVE Static Data Exports. MariaDB conversions of this data is available at https://www.fuzzwork.co.uk/dump/ and used in SeAT.

+

To update to the latest SDE within SeAT, run:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde'
+
+

Supervisor

+

The jobs ecosystem within SeAT requires a process supervisor to ensure that the job runner stays alive. The job runner itself is implemented using Laravel Horizon and is monitored using supervisord.

+

To configure the Horizon process monitor, first install supervisor:

+
apt-get install supervisor
+
+

Next, we will create a dedicated configuration file which will ask supervisor to keep an eye on Horizon. This file will live in /etc/supervisor/conf.d/seat.conf. Create this file with its recommended configuration with:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
cat > /etc/supervisor/conf.d/seat.conf << EOL
+[program:seat]
+command=/usr/bin/php /var/www/seat/artisan horizon
+process_name = %(program_name)s-80%(process_num)02d
+stdout_logfile = /var/log/seat-80%(process_num)02d.log
+stdout_logfile_maxbytes=100MB
+stdout_logfile_backups=10
+numprocs=1
+directory=/var/www/seat
+stopwaitsecs=600
+user=www-data
+EOL
+
+

Finally, reload supervisor to apply the new configuration with the following command:

+
systemctl enable supervisor.service
+
+

Crontab

+

A crontab entry is needed for SeAT. While simple in implementation, this crontab entry simply helps the application invoke a job checker very minute. The actual schedule is stored within SeAT itself and managed entirely via the Web Interface.

+

To configure the crontab entry required for SeAT, run the following commands:

+
echo '* * * * * php /var/www/seat/artisan schedule:run >> /dev/null 2>&1' > /tmp/seat-crontab.tmp
+
+

Next, add this crontab for the www-data user with:

+
crontab -u www-data /tmp/seat-crontab.tmp
+
+

If you want to confirm that the crontab successfully installed, you can check it with crontab -u www-data -l.

+

Web Server

+
+

Almost there!

You almost made it to the end! Just one more step.

+

+
+

The SeAT web interface requires a web server to serve the HTML goodies it has. We highly recommend you to use nginx and will be covered in this document. You don't have to use it, so if you prefer something else, feel free.

+

Nginx Install

+

Together with an nginx installation we also need to install php-fpm to handle the PHP execution for us. Let's install nginx and php-fpm with:

+
apt-get install nginx php8.2-fpm
+
+

Nginx Configuration

+

With the webserver installed, we need to configure nginx to serve SeAT. For that, a configuration file needs to be created that will tell nginx where to find php-fpm as well as where the assets are for SeAT.

+

The configuration file will live at /etc/nginx/sites-available/seat. It can be created with the following command:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
cat > /etc/nginx/sites-available/seat << EOL
+server {
+
+    listen 80;
+    listen [::]:80;
+
+    # If you are hosting this instance on a domain, set that
+    # name here.
+    #server_name  seat.yourdomain.com;
+
+    # SeAT public directory. This is the only directory that
+    # should be exposed by the webserver. If one has to expose
+    # the parent directory then things like the .env file will
+    # be available for anyone to download.
+    root /var/www/seat/public;
+
+    index index.php;
+
+    location / {
+       try_files \$uri \$uri/ /index.php?\$query_string;
+    }
+
+    # PHP-FPM configuration.
+    location ~ \.php\$ {
+       try_files \$uri /index.php =404;
+       fastcgi_pass unix:/run/php/php8.2-fpm.sock;
+       fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
+       include fastcgi_params;
+    }
+
+    # Even though .htaccess rules mean nothing in the nginx
+    # world, prevent those from being downloaded anyways.
+    location ~ /\.ht {
+       deny all;
+    }
+
+    # In case someone messes up, prevent .env files from
+    # being downloaded as well.
+    location ~ /\.env {
+       deny all;
+    }
+}
+EOL
+
+
+

Warning

+

The code block above should not be copied directly into a file. It is a script and should be pasted directly into the linux terminal. It will create the nginx config for you. If you create the file yourself with the above content then the file will not be valid and you will receive errors from nginx.

+
+

The configuration file as is at /etc/nginx/sites-available/seat itself won't be loaded by nginx yet. Storing configuration files in a *sites-available* directory is simply a convention used to allow administrators to quickly add & remove sites if needed. To apply the changes made by the new configuration file it needs to be symlinked to a *sites-enabled* directory.

+

Let's symlink to the new configuration and drop the default one as a hardening exercise at the same time:

+
1
+2
ln -s /etc/nginx/sites-available/seat /etc/nginx/sites-enabled/seat
+rm /etc/nginx/sites-enabled/default
+
+

Finally, reload nginx and php-fpm for the new changes to take affect:

+
1
+2
systemctl restart nginx.service
+systemctl restart php8.2-fpm.service
+
+

ESI Configuration

+

As mentioned at the start of the guide, it is necessary for you to configure ESI. +For instructions how to do this, please refer to the ESI Setup Guide.

+
+

Info

+

You may want to serve your SeAT installation over SSL (using HTTPS) - which is a recommanded behavior. +There are many way to do it, you can have a look on Let's Encrypt which provide you valid certificates for free. +Put an eye to their Certbot Documentation.

+
+
+

Success

+

You made it! Use a browser and browse to the IP address / hostname of your server to access SeAT!

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/installation/old_versions/docker_installation_seat_4/index.html b/installation/old_versions/docker_installation_seat_4/index.html new file mode 100644 index 00000000..b290f906 --- /dev/null +++ b/installation/old_versions/docker_installation_seat_4/index.html @@ -0,0 +1,1688 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Docker Installation (4.x) - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Docker

+

Docker is ideally the installation route you want to go. Docker enables us to run SeAT on any platform capable of running docker itself (which includes Windows!). Additionally, upgrades and service maintenance are really low effort as you don't have to care about any dependencies. All of it is maintained within a docker stack and dockerhub.

+
+

Info

+

If you plan on running Docker on Windows, for the best performance it is suggested that you run Docker using the Windows Subsystem for Linux 2 (WSL2) backend, available starting in Windows 10/Windows Server 20H1 (build 2004) releases.

+
+
+

Hint

+

Before starting the installation process, be sure you read this complete document first. It will help you understand all of the steps from an installation process.

+

If you feel like docker might not be your cup of tea, checkout some of the other getting started guides that are available.

+
+
+

Warning

+

If you are using Docker on Windows, you will need to use the Manual Deployment option below.

+
+
+

Eve Application and ESI

+

SeAT used CCP's ESI service in order to retrieve EVE Online-related information. Before you can make any authenticated calls to ESI, you have to register a third-party EVE application on the developers portal. This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

+
+

Internal Container Setup Overview

+

The setup for SeAT's docker installation orchestrated using docker-compose. With docker-compose, we can use a single docker-compose.yml file to define the entire stack complete with all of the dependencies required to run SeAT. A pre-built and recommended compose file (which is also used by the bootstrapping script) is hosted in the seat-docker repository here.

+

The previously mentioned compose file is really simple. A high-level overview of its contents is:

+
    +
  • A single docker network called seat-network is defined. All containers are connected to this network and is used as the primary means for inter-container communications.
    • +
  • A single volume called mariadb-data is defined. This is the most important volume as it contains all of the database data. This is the one volume that you should configure a backup solution for!
    • +
  • Six services (or containers) are used within the SeAT docker stack. Three services use basic images pulled directly from Dockerhub and three others use a custom-built image, also hosted on DockerHub. The container images used are:
    • +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Image NameImage Repository
mariadb:10https://hub.docker.com/_/mariadb/
redis:5-alpinehttps://hub.docker.com/_/redis/
traefik:2.2https://hub.docker.com/_/traefik
eveseat/seathttps://hub.docker.com/r/eveseat/seat
+
    +
  • The environment is configured using a top-level .env file (not to be confused with the SeAT specific .env file.
    • +
  • Only two ports are exposed by default. Those are tcp/80 and tcp/443. These can be connected to in order to access the SeAT web interface.
    • +
  • All containers are configured to restart on failure, so if your server reboots or a container dies for whatever reason it should automatically start up again.
    • +
+

SeAT Docker Installation

+

Depending on whether you already have docker and docker-compose already installed, you may choose how to start the installation. If you already have the required tooling installed and running their latest versions, all you need to do is download the latest docker-compose.yml and .env files to get started.

+

Automated Setup Script

+

If you do not have the required software installed yet, consider running the bootstrap script that will check for docker and docker-compose, install it and start the SeAT stack up for you. The script can be run with:

+
bash <(curl -fsSL https://git.io/get-seat)
+
+

Once the script is finished, you can skip to the monitoring the stack section of this guide.

+

If you don't want to run this script, follow along in the next section of this guide.

+

Manual Deployment

+

Docker Download

+

If you do not have docker, install it now with the following command as root:

+
sh <(curl -fsSL get.docker.com)
+
+

If you are on Windows, download and install Docker Desktop.

+

Docker-compose Download

+

If you do not have docker-compose, install it now with the following command as root (Docker Compose is included with Docker Desktop on Windows):

+
1
+2
+3
+4
+5
# Downloads docker-compose
+curl -L https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
+
+# Makes docker-compose executable
+chmod +x /usr/local/bin/docker-compose
+
+

Docker compose working directory

+

With docker and docker-compose ready, create yourself a directory in /opt with mkdir -p /opt/seat-docker and cd to it. Remember this directory as you will need to come back to it often.

+

On Windows, create the C:\seat-docker directory with mkdir C:\seat-docker and cd to it.

+

SeAT docker-compose.yml and .env File

+

Then, download the docker-compose.yml file with:

+
+
+
+
curl -fsSL https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -o docker-compose.yml
+
+
+
+
Invoke-WebRequest -Uri https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -OutFile docker-compose.yml
+
+
+
+
+

Next, download the docker .env file with:

+
+
+
+
curl -fsSL https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -o .env
+
+
+
+
Invoke-WebRequest -Uri https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -OutFile .env
+
+
+
+
+

Next, we will generate a unique application key - this is used internally for encryption:

+
+
+
+
sed -i -- 's/APP_KEY=insecure/APP_KEY='$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c32 ; echo '')'/g' .env
+
+
+
+
$appkey = (-join ((65..90) + (97..122) | Get-Random -Count 32 | % {[char]$_})); (Get-Content .env -Raw) -replace "APP_KEY=insecure", "APP_KEY=$appkey" | Set-Content .env
+
+
+
+
+

SeAT docker configuration

+

Open up the .env file in a text editor and fill in a few of the configuration items needed.

+

TRAEFIK_DOMAIN should be set to the base domain your installation lives on.
+SEAT_SUBDOMAIN sould be the subdomain for the SeAT web UI. eg: seat.domain.local

+

For TLS configuration, you need to set the TRAEFIK_ACME_EMAIL value, and then in the docker-compose.yml file uncomment the labels that relating to certResolver. They typically look like this: traefik.http.routers.api.tls.certResolver=primary. Finally, create an ACME configuration file with:

+
1
+2
+3
mkdir acme
+touch acme/acme.json
+chmod 600 acme/acme.json
+
+
+

Info

+

SeAT docker template is shipped with Traefik to hide your container behind a proxy and securing traffic up to it. In case you want to manage traffic proxying and certification on your own, you can disable traefik container from the stack by adding # [front of lines] from the docker-compose.yml file.

+
+
+

Warning

+

The location of the docker-compose.yml and .env files are important. You need to cd back to the directory where these are stored in order to be able to execute commands for this stack at a later stage.

+

Also, be sure you provide a valid e-mail address as it will be used to register your account against Let's Encrypt. For those unfamiliar with this, it's CA that provides valid certificates for free.

+
+

ESI Configuration

+

As mentioned at the start of the guide, it is necessary for you to configure ESI. For instructions on how to do this, please refer to the ESI Setup Guide.

+

With the configuration files ready, start up the stack with:

+
docker-compose up -d
+
+

Monitoring the Stack

+

Knowing what is going on inside of your containers is crucial to understanding how everything is running as well as useful when debugging any problems that may occur. While the containers are starting up or have been running for a while, you can always cd to the directory where your docker-compose.yml file lives and run the logs command to see the output of all of the containers in the stack. For example:

+
1
+2
cd /opt/seat-docker
+docker-compose logs --tail 10 -f
+
+

These commands will cd to the directory containing the stacks docker-compose.yml file and run the logs command, showing the last 10 log entries and then printing new ones as they arrive.

+

Configuration Changes

+

All of the relevant configuration lives inside the .env file, next to your docker-compose.yml file. Modify their values by opening it in a text editor, making the appropriate changes, and saving it again. Once that is done, run docker-compose up -d again to restart the container environment.

+
+

Success

+

You made it! Use a browser and browse to the domain / subdomain of your server to access SeAT!

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/installation/old_versions/manual_installation_seat_4/index.html b/installation/old_versions/manual_installation_seat_4/index.html new file mode 100644 index 00000000..2a14e725 --- /dev/null +++ b/installation/old_versions/manual_installation_seat_4/index.html @@ -0,0 +1,2181 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Manual Installation (4.x) - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Manual Installation

+

This guide attempts to explain how to manually install SeAT onto an Ubuntu Server. +A small amount of Linux experience is preferred when it comes to this guide, although it is not entirely mandatory.

+
+

Info

+

This guide has been written targetting Ubuntu. However, you can use it to deploy SeAT on any linux distribution. +Just be sure you adapt commands to targetted distribution (mostly those related to the package manager).

+
+
+

Hint

+

Before starting to do anything, be sure you read the complete workflow once. +It will help you to understand all steps from the installation process.

+
+
+

Eve Application and ESI

+

SeAT consumes CCP's ESI service in order to retrieve EVE Online related information. +Before you can make any authenticated calls to ESI, you have to register a third party EVE application on the developers portal. +This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

+
+

Getting started

+

We are going to assume you have root access to a fresh Ubuntu Server. +Typically access is gained via SSH. +All of the below commands are to be entered in the SSH terminal session for the installation & configuration of SeAT. +If the server you want to install SeAT on is being used for other things too (such as hosting MySQL databases and or websites), then please keep that in mind while following this guide.

+

Packages are installed using the aptitude package manager as the root user.

+

OS Installation

+

Operating System

+

Before we get to installing SeAT, lets ensure that your operating system is up to date. We can do that with basics :

+
    +
  • apt-get update to refresh the repositories cache.
    • +
  • apt-get full-upgrade to update any installed packages.
    • +
  • reboot in order to ensure any updated software is the current running version.
    • +
  • apt-get autoremove (after the reboot) to cleanup any unneeded packages.
    • +
+

Database

+

SeAT relies heavily on a database to function. Everything it learns is stored here, along with things such as user accounts for your users. +It comes without saying that database security is a very important aspect too. So, ensure that you choose very strong passwords for your installation where required.

+

This document describes using MariaDB, but you can use MySQL as well. Just double check the requirements.

+

We need to ensure that we have the latest MariaDB installed. To help with this, MariaDB provides an official repository to get the latest versions. +Let's add this repository with:

+
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | bash
+
+

With the repository now setup, lets install the database server:

+
+

Warning

During the installation, you may be asked to set a password for the root MariaDB user account. +Make sure you set a long, strong password and remember it. It will be needed for the next step.

+

+
+
apt-get install mariadb-server
+
+

Next, we are going to secure the database server by removing anonymous access and setting a root password (if you have not been prompted for it yet).

+
+

Note

+

The database root password should not be confused with the operating systems root passwords. They are both completely different. +They should also not have the same password.

+
+

To secure the database, run:

+
mysql_secure_installation
+
+

This will ask you a series of questions where you should generally just answer yes to. If you already set a root password in the previous step then you dont have to set it again, otherwise, make sure you choose a long, strong password for the root account. An example run is shown below:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
[...]
+
+Enter current password for root (enter for none):  IF ONE WAS SET, IGNORE THIS
+OK, successfully used password, moving on...
+
+[...]
+
+Set root password? [Y/n] y
+New password:             SET A STRONG PASSWORD HERE
+Re-enter new password:    SET A STRONG PASSWORD HERE
+Password updated successfully!
+Reloading privilege tables..
+ ... Success!
+
+[...]
+
+Remove anonymous users? [Y/n] y
+ ... Success!
+
+[...]
+
+Disallow root login remotely? [Y/n] y
+ ... Success!
+
+[...]
+
+Remove test database and access to it? [Y/n] y
+
+[...]
+
+Reload privilege tables now? [Y/n] y
+ ... Success!
+
+[...]
+
+

That concludes the installation of the database server and securing it.

+

Next, we need to create an actual user and database for SeAT to use on the newly installed server. To do this we use the mysql command line client and enter a few commands as the root user to create the database and the user that will be accessing the server. Let get to it.

+

Fire up the mysql client as root by running:

+
mysql -uroot -p
+
+

This will prompt you for a password. Use the password you configured for the root account when we ran mysql_secure_installation. This will most probably be the last time you need to use this password :)

+

If the password was correct, you should see a prompt similar to the one below:

+
1
+2
+3
+4
+5
+6
+7
+8
+9
root@ubuntu:~# mysql -uroot -p
+Enter password:
+Welcome to the MariaDB monitor.  Commands end with ; or \g.
+Your MariaDB connection id is 16
+Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+MariaDB [(none)]>
+
+

Create a new database for SeAT to use with:

+
create database seat;
+
+

The output should be similar to the below:

+
1
+2
MariaDB [(none)]> create database seat;
+Query OK, 1 row affected (0.00 sec)
+
+

Next, we need to create the user that SeAT itself will use to connect and use the new seat database:

+
GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';
+
+

Of course, you need to replace s_p3rs3c3r3tp455w0rd with your own unique and strong password. +Successfully running this should present you with output similar to the below:

+
1
+2
MariaDB [(none)]> GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';
+Query OK, 0 rows affected (0.00 sec)
+
+

In the example above, we have effectively declared that SeAT will be using the database as seat:s_p3rs3c3r3tp455w0rd@localhost/seat.

+

Finally, we will flush the database server privileges:

+
FLUSH PRIVILEGES;
+
+

That concludes the database server setup. You can exit the prompt with exit;

+
+

Note

+

Remember the password for the seat database user as we will need it later to configure SeAT.

+
+

PHP

+

Since SeAT is written primarily in PHP, we will need to install PHP packages. Ubuntu based systems can make use of the ondrej PPA which is a very popular repository used for specific PHP versions.

+

Depending on the version of Ubuntu you are using, a release specific repository URL should be used for the PPA. Select the tab applicable to your Ubuntu version and run the commands within.

+
+
+
+
1
+2
echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu bionic main" >> /etc/apt/sources.list.d/php.list
+echo "deb-src http://ppa.launchpad.net/ondrej/php/ubuntu bionic main" >> /etc/apt/sources.list.d/php.list
+
+
+
+
1
+2
echo "deb http://ppa.launchpad.net/ondrej/php/ubuntu focal main" >> /etc/apt/sources.list.d/php.list
+echo "deb-src http://ppa.launchpad.net/ondrej/php/ubuntu focal main" >> /etc/apt/sources.list.d/php.list
+
+
+
+
+

Next, we will have to download the new repositories GPG signing key and add it into our keychain

+
apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 4F4EA0AAE5267A6C
+
+

With the new repository configured, update the package lists with:

+
apt-get update
+
+

Finally, install the required PHP packages with:

+
1
+2
apt-get install libpng-dev libfreetype6-dev libjpeg-dev
+apt-get install curl openssl zip php7.3-bz2 php7.3-cli php7.3-curl php7.3-dom php7.3-gd php7.3-gmp php7.3-intl php7.3-mbstring php7.3-mysql php7.3-opcache php7.3-redis php7.3-zip
+
+

Redis

+

SeAT makes use of Redis as a cache and message broker for the Queue back end. Installing it is really easy. Do it with:

+
apt-get install redis-server
+
+
+

Hint

+

By default, redis is making backup from its database - so it ensure integrity in case of failure. +However, in certain condition, like power outage, this backup might be unprocessable and avoid redis to run.

+

Since we don't store anything critical in it, you may want to disable this. To do so, edit the configuration file +using nano /etc/redis/redis.conf and search line appendonly no, change it for appendonly yes

+

If you are on a small server, You may also want to limit the part of memory used by redis (by default, it will consume all available memory). +To do so, into the redis configuration file, search line # maxmemory <bytes> and change it for maxmemory xGB where x is the memory limit you want to set.

+
+

SeAT Installation

+

Prerequisites

+

Excellent progress! All of the operating system level requirements are now met and we are almost ready to install SeAT itself. The only thing that is outstanding is the package manager called composer as well as the git client. The combination of composer and git will let us download the SeAT source code from Github and install it locally.

+

Git

+

Install git with:

+
apt-get install git
+
+

Composer

+

Next, install composer with:

+
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && hash -r
+
+

Thats it. Lets install SeAT! By default, we suggest you run SeAT from within /var/www/seat. As part of the installation, the seat directory will be created for us, but we will need to create /var/www for now as we have not yet configured the web server.

+

Create the www directory with:

+
mkdir -p /var/www
+
+

Next, cd to the new /var/www directory with:

+
cd /var/www
+
+

SeAT Download

+

With all of the prerequisites installed as well as our www directory ready we can finally download SeAT. Do that with:

+
composer create-project eveseat/seat --no-dev --no-interaction
+
+

Once the download is done, you should have seen output such as:

+
Writing lock file
+Generating optimized autoload files
+> Illuminate\Foundation\ComposerScripts::postAutoloadDump
+> @php artisan package:discover
+Discovered Package: darkaonline/l5-swagger
+Discovered Package: eveseat/api
+Discovered Package: eveseat/console
+Discovered Package: eveseat/eveapi
+Discovered Package: eveseat/notifications
+Discovered Package: eveseat/services
+Discovered Package: eveseat/web
+Package manifest generated successfully.
+> @php artisan key:generate
+Application key [base64:CmhqYNkaIcHo8nYC8LiEWa3U5/+BiTLih5dZftxlV2k=] set successfully.
+
+

Permissions

+

You may have noticed a warning about composer running as root. For now this can be safely ignored. Post the installation of the SeAT source code, we need to fix up the permissions of the downloaded files. Do that with:

+
1
+2
chown -R www-data:www-data /var/www/seat
+chmod -R guo+w /var/www/seat/storage/
+
+

This will ensure that the web server, cron jobs and workers have access to the source code as well as logs.

+

SeAT Setup

+

With SeAT downloaded, we need to configure it. There are a number of configuration tasks needed. These include editing the applications .env file as well as running some commands that setup and seed the database. A configuration value reference can be found here.

+

.env setup

+

The first task would be to configure the applications database connection. Open the file located at /var/www/seat/.env with something like vi or nano and update the database options with your values. Typically, only the password would really need to be updated. If you are making use of an existing database somewhere else over the network, update the applicable fields such as DB_HOST accordingly.

+
1
+2
+3
+4
+5
+6
+7
DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=seat
+DB_USERNAME=seat
+DB_PASSWORD=s_p3rs3c3r3tp455w0rd # <-- this is the value you probably need to edit.
+DB_DEBUG=false
+
+

Database Migrations and Seeds

+

Next we need to publish the database migrations and web assets (such as JavaScript scripts and CSS Style sheets), run those migrations and finally seed the SeAT job schedule.

+

Publish the assets and database migrations with:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'
+
+

Run the database migrations with:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'
+
+

Seed the SeAT schedule with:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\Console\\database\\seeds\\ScheduleSeeder'
+
+

EVE Sde Update

+

SeAT makes use of a number of tables from the EVE Static Data Exports. MySQL conversions of this data is available at https://www.fuzzwork.co.uk/dump/ and used in SeAT.

+

To update to the latest SDE within SeAT, run:

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde'
+
+

Supervisor

+

The jobs ecosystem within SeAT requires a process supervisor to ensure that the job runner stays alive. The job runner itself is implemented using Laravel Horizon and is monitored using supervisord.

+

To configure the Horizon process monitor, first install supervisor:

+
apt-get install supervisor
+
+

Next, we will create a dedicated configuration file which will ask supervisor to keep an eye on Horizon. This file will live in /etc/supervisor/conf.d/seat.conf. Create this file with its recommended configuration with:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
cat > /etc/supervisor/conf.d/seat.conf << EOL
+[program:seat]
+command=/usr/bin/php /var/www/seat/artisan horizon
+process_name = %(program_name)s-80%(process_num)02d
+stdout_logfile = /var/log/seat-80%(process_num)02d.log
+stdout_logfile_maxbytes=100MB
+stdout_logfile_backups=10
+numprocs=1
+directory=/var/www/seat
+stopwaitsecs=600
+user=www-data
+EOL
+
+

Finally, reload supervisor to apply the new configuration with the following command:

+
systemctl restart supervisor.service
+
+

Crontab

+

A crontab entry is needed for SeAT. While simple in implementation, this crontab entry simply helps the application invoke a job checker very minute. The actual schedule is stored within SeAT itself and managed entirely via the Web Interface.

+

To configure the crontab entry required for SeAT, run the following commands:

+
echo '* * * * * php /var/www/seat/artisan schedule:run >> /dev/null 2>&1' > /tmp/seat-crontab.tmp
+
+

Next, add this crontab for the www-data user with:

+
crontab -u www-data /tmp/seat-crontab.tmp
+
+

If you want to confirm that the crontab successfully installed, you can check it with crontab -u www-data -l.

+

Web Server

+
+

Almost there!

You almost made it to the end! Just one more step.

+

+
+

The SeAT web interface requires a web server to serve the HTML goodies it has. We highly recommend you to use nginx and will be covered in this document. You don't have to use it, so if you prefer something else, feel free.

+

Nginx Install

+

Together with an nginx installation we also need to install php-fpm to handle the PHP execution for us. Let's install nginx and php-fpm with:

+
apt-get install nginx php7.3-fpm
+
+

Nginx Configuration

+

With the webserver installed, we need to configure nginx to serve SeAT. For that, a configuration file needs to be created that will tell nginx where to find php-fpm as well as where the assets are for SeAT.

+

The configuration file will live at /etc/nginx/sites-available/seat. It can be created with the following command:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
cat > /etc/nginx/sites-available/seat << EOL
+server {
+
+    listen 80;
+    listen [::]:80;
+
+    # If you are hosting this instance on a domain, set that
+    # name here.
+    #server_name  seat.yourdomain.com;
+
+    # SeAT public directory. This is the only directory that
+    # should be exposed by the webserver. If one has to expose
+    # the parent directory then things like the .env file will
+    # be available for anyone to download.
+    root /var/www/seat/public;
+
+    index index.php;
+
+    location / {
+       try_files \$uri \$uri/ /index.php?\$query_string;
+    }
+
+    # PHP-FPM configuration.
+    location ~ \.php\$ {
+       try_files \$uri /index.php =404;
+       fastcgi_pass unix:/run/php/php7.3-fpm.sock;
+       fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
+       include fastcgi_params;
+    }
+
+    # Even though .htaccess rules mean nothing in the nginx
+    # world, prevent those from being downloaded anyways.
+    location ~ /\.ht {
+       deny all;
+    }
+
+    # In case someone messes up, prevent .env files from
+    # being downloaded as well.
+    location ~ /\.env {
+       deny all;
+    }
+}
+EOL
+
+
+

Warning

+

The code block above should not be copied directly into a file. It is a script and should be pasted directly into the linux terminal. It will create the nginx config for you. If you create the file yourself with the above content then the file will not be valid and you will receive errors from nginx.

+
+

The configuration file as is at /etc/nginx/sites-available/seat itself won't be loaded by nginx yet. Storing configuration files in a *sites-available* directory is simply a convention used to allow administrators to quickly add & remove sites if needed. To apply the changes made by the new configuration file it needs to be symlinked to a *sites-enabled* directory.

+

Let's symlink to the new configuration and drop the default one as a hardening exercise at the same time:

+
1
+2
ln -s /etc/nginx/sites-available/seat /etc/nginx/sites-enabled/seat
+rm /etc/nginx/sites-enabled/default
+
+

Finally, reload nginx and php-fpm for the new changes to take affect:

+
1
+2
systemctl restart nginx.service
+systemctl restart php7.3-fpm.service
+
+

ESI Configuration

+

As mentioned at the start of the guide, it is necessary for you to configure ESI. +For instructions how to do this, please refer to the ESI Setup Guide.

+
+

Info

+

You may want to serve your SeAT installation over SSL (using HTTPS) - which is a recommanded behavior. +There are many way to do it, you can have a look on Let's Encrypt which provide you valid certificates for free. +Put an eye to their Certbot Documentation.

+
+
+

Success

+

You made it! Use a browser and browse to the IP address / hostname of your server to access SeAT!

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/installation/requirements/index.html b/installation/requirements/index.html new file mode 100644 index 00000000..921ed0a0 --- /dev/null +++ b/installation/requirements/index.html @@ -0,0 +1,1676 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Requirements - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Requirements

+

Hardware Requirements

+

As far as hardware goes, there isn't really a hard and fast rule on what is needed. +The more resources you make available, the faster API updates will occur. +However, there are some minimum recommended specifications.

+
+

Info

+

Required CPU cores are indicative and may changes depending on your processor. +They have been based on a one tier deployment (app, workers and database are hosted on the same server).

+

To improve accuracy regarding CPU requirements, we provide a Coremark value. +Since Cloud providers like Azure and Google Cloud are providing their instance benchmark using this test, it should give you a more meaningful idea of what we are talking about.

+
+
+

Warning

+

If you intend to process a large amount of data, plan your storage accordingly. +The SeAT database can grow incredibly quickly depending on the amount of tokens you process.

+

Due to high I/O traffic generated by SeAT, we recommand NVMe storage usage for best performances.

+
+

Up to 25 characters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeRequirement
CPU2 virtual cores (Coremark 20 000+)
Memory2GB of RAM with a swap file
Core Storage Space1GB (tend to be stable)
ESI Cache Storage Space2GB (tend to grow with characters)
Database Storage Space5GB (tend to grow with characters and history)
+

Up to 500 characters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeRequirement
CPU2 virtual cores (Coremark 20 000+)
Memory4GB of RAM
Core Storage Space1GB (tend to be stable)
ESI Cache Storage Space5GB (tend to grow with characters)
Database Storage Space10GB (tend to grow with characters and history)
+

Up to 1 000 characters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeRequirement
CPU4 virtual cores (Coremark 40 000+)
Memory8GB of RAM
Core Storage Space1GB (tend to be stable)
ESI Cache Storage Space10GB (tend to grow with characters)
Database Storage Space20GB (tend to grow with characters and history)
+

More than 1 000 characters

+

If you plan to run SeAT for more than 1 000 characters, you will have to fine tune your installation and carefully monitoring it. +At time this documentation is wrote, a standard character is queuing around 50 jobs per wave. +Since all jobs are not doing the same thing, it's difficult to provide you accurate figures.

+

A single worker is consuming around 200 MB of memory. Most jobs are requiring less than 5% of CPU - however, a few of them need more than 20% of it. +The more jobs you'll get, the more workers you'll need to process queue in less than 60 minutes.

+
+

Warning

+

With such installation, you shouldn't share SeAT server resources with other services. +Also, you should consider deploying database on another server.

+
+

Software Requirements

+

Docker Environment

+

For Docker based installations, all you need is docker. +If you already have it installed, check your current version with docker version.

+ + + + + + + + + + + + + + + +
TypeRequirementVersion Check
DockerDocker: ^24.0docker -v
+
+

Info

+

If you plan to deploy SeAT on a Windows host, you will need Docker for Windows

+
+
+

Warning

+

Do not install Docker directly from your distributions repositories. These are usually out of date. +Instead, rather follow the steps provided on dockers official documentation

+

When considering a VPS provider, make sure you choose one that does not make use of OpenVZ or similar operating-system level virtualization technologies. These virtualization technologies limit you in terms of kernel access as they purely containerize an existing Linux installation.

+

For a successful docker installation, choose a provider that uses para-virtualized technologies such as KVM, VMWare or XEN allowing you full control to the instance (and therefor the kernel itself). Examples of such providers are Digital Ocean, Linode and Vultr.

+
+

Bare metal Environment

+
+

Info

+

We consider "bare metal", any environment on which SeAT has been deployed manually (instead using containers).

+

If you plan to deploy SeAT on a Windows host, you will have to use Docker

+
+

Software version requirements are based on a minimum requirement.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeRequirementState Check
Operating SystemLinux (any distribution is suitable, however, Ubuntu tends to get more up-to-date packages on official repositories).Usually, running cat /etc/issue should give you a good idea.
Architecture64-bit onlyuname -p
PHPPHP: ^8.3 including mysql, gd, bz2, intl, pcntl, gmp, openssl, zip, opcache and redis extensionsphp -v and php -i
DatabaseMariaDB: ^10.2.7mysql -V
Caching ServiceRedisredis-server -v
Service SupervisorSupervisor : 3supervisord -v
Web ServerNGinX or Apachenginx -v or httpd -v
+
+

Tip

+

In case you want to deploy SeAT with Apache as web server, plan to configure it with Fast CGI using php-fpm instead embedded php process. +Doing it so will make you benefit of significant improved performances.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/search/search_index.json b/search/search_index.json new file mode 100644 index 00000000..b20d8c2b --- /dev/null +++ b/search/search_index.json @@ -0,0 +1 @@ +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":""},{"location":"#home","title":"Home","text":"

Welcome to the SeAT documentation pages!

This site aims to provide you with useful, technical information about SeAT. Please refer to the index on the side for detailed installation instructions, documentation about SeAT internals and/or development guidelines!

Contributing to Documentation

Great software is coupled with even greater documentation. If you would like to contribute to making this documentation even better, please don't hesitate to fork the documentation repository and submit a pull request with your contribution. We are always looking for better information.

"},{"location":"#quick-start","title":"Quick Start","text":"

There are many ways to install SeAT. In all cases you will need a dedicated server as a minimum. Using the docker installation you are free to choose any Docker capable host (yes, even Windows!). However, if you choose to install SeAT on bare metal, you'll need a linux distribution. We suggest you choose an LTS version of Ubuntu, Debian or CentOS.

"},{"location":"#installation-options","title":"Installation Options","text":"

Ignoring the details, to get SeAT installed quickly you have a few options. All of them will get you SeAT installed, but you still have to manually configure an SSO application on the EVE Online Developers Portal.

Method Comments Docker Follow our docker installation guide. This is the recommended way to install SeAT as it will handle near everything for you. Manually You can always install SeAT by following our manual installation guide. All you need is PHP, MariaDB, Redis and a web server and some Linux experience.

Warning

While installing SeAT - choose one method, and stick to it. Otherwise, you'll get SeAT installed multiple times.

"},{"location":"#upgrades-updates","title":"Upgrades / Updates","text":"

SeAT is being worked on continuously. New features are added, performance improvements are made and bugs are fixed. If you wish to upgrade to the latest version of SeAT refer to the upgrade section.

"},{"location":"#contact","title":"Contact","text":"

Want to get in touch with developers, or just other users of SeAT? Refer to the contact section to find out how!

"},{"location":"community_packages/","title":"Community Packages","text":""},{"location":"community_packages/#community-packages","title":"Community Packages","text":"

Below is a list of packages contributed by the community. These packages normally follow the same installation procedure, however, its best you consult the documentation of the package itself in case there is anything special you need to get it working.

"},{"location":"community_packages/#blade-package-installation","title":"Blade package installation","text":"

Packages will normally come in the form of a composer package that you need to include in your SeAT install, as well as a Service Provider that you need to bootstrap. So, generically speaking, installing a package will mean that you:

  • Ensure that you are in the path where you installed. By default, this should be /var/www/seat.

  • Put your application into maintenance mode. This will ensure that no request from the outside will hit your applications logic, and also help you perform an upgrade uninterrupted. Do this with the following commands issued as the webserver user:

sudo -H -u www-data bash -c 'php artisan down'\n
  • Require the package via composer:
sudo -H -u www-data bash -c 'composer require <package vendor>/<package-name>'\n
  • Publish the assets with artisan:
sudo -H -u www-data bash -c 'php artisan vendor:publish --force --all'\n
  • Run migration in order to update database:
sudo -H -u www-data bash -c 'php artisan migrate'\n
  • Renew config and route cache to benefit of newly added functionalities:
sudo -H -u www-data bash -c 'php artisan route:cache'\nsudo -H -u www-data bash -c 'php artisan config:cache'\n
  • Clear SeAT cache after installation:
sudo -H -u www-data bash -c 'php artisan seat:cache:clear'\n
  • Bring your application live and back out of maintenance mode:
sudo -H -u www-data bash -c 'php artisan up'\n

Installing packages like this will ensure that none of the core SeAT packages are affected and you should be free to upgrade SeAT core at anytime.

"},{"location":"community_packages/#docker-package-installation","title":"Docker package installation","text":"

Applying community packages to your SeAT instance with Docker requires you to update your .env file located in /opt/seat-docker and uncommenting SEAT_PLUGINS by removing '#' and entering the package(s) to be installed separating each package with a comma. An example of how to enter packages in your .env would be:

# SeAT Plugins\n# This is a list of the all of the third party plugins that you\n# would like to install as part of SeAT. Package names should be\n# comma seperated if multiple packages should be installed.\nSEAT_PLUGINS=denngarr/seat-fitting,cryptaeve/seat-squad-sync\n
  • Once you have entered the package(s) to be installed run the below command in /opt/seat-docker:
Docker (SeAT 4.x)Docker (SeAT 5.x - using Traefik)Docker (SeAT 5.x - using reverse proxy) 
docker-compose up -d\n
docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n
docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n

After running the above command wait for containers affected to rebuild. If SeAT does not come back up refer to Troubleshooting for more insight.

"},{"location":"community_packages/#package-list","title":"Package list","text":""},{"location":"community_packages/#seat-specific-packages","title":"SeAT specific packages","text":""},{"location":"community_packages/#maintained-packages","title":"Maintained packages","text":"Package Version (SeAT 4.x) Version (SeAT 5.x) Installation Description alliancewaw/seat-mumble-register Read the docs This plugin provide an extension to generate a certificate for SeAT user and regist it to mumble server cryocaustik/seat-hr Human Resources plugin for SeAT with Applications (with customized questions per corporation), Blacklist, Intel, Kick History, Notes, and Sheet cryptaeve/seat-squad-sync Adds the ability to sync squad members into filters of permissions cryptaeve/seat-text A module to serve public static ascii, with editing access controlled by seat denngarr/seat-fitting Module to check fittings per character denngarr/seat-srp A module for SeAT that tracks SRP requests h4zz4rddev/seat-buyback A SeAT module for buyback functionality humunuk/alliance-structure-mngmt Add \"Structures\" sub-menu to Alliance page and show all the structures that belong to corps in alliance kassie/calendar Read the docs Calendar plugin pyTonicis/seat-corp-mining-tax Read the docs A Modul to manage corporation mining tax warlof/seat-discord-connector Read the docs A Discord driver to be used with seat-connector warlof/seat-teamspeak Read the docs A Teamspeak driver to be used with seat-connector recursivetree/seat-info Read the docs A module that adds a small wiki-like article systems for example as a corporation bulletin.SeAT 5.xYou need to follow special steps after upgrading to retain your resource files. recursivetree/seat-rat A module to monitor ratting usage in a system, e.g. to prevent dropping the bounty risk modifier in nullsec. simplyunnamed/seat-user-last-login Tool to help find potential AFK's in your corporation. recursivetree/seat-billing A billing module to help you with ore and rating taxes. recursivetree/seat-pushx-blamer A module to tell you who's guilty of blocking the PushX queue. recursivetree/seat-alliance-industry A corporation/alliance/coalition industry order marketplace recursivetree/seat-inventory Inventory manager for contracts and corporation hangars. recursivetree/seat-transport This plugin is a calculator for hauling costs, for example for an alliance JF service. recursivetree/seat-mineral-hauling Calculates the most efficient way to move minerals in refined ore form."},{"location":"community_packages/#price-provider-packages","title":"Price Provider Packages","text":"

These packages implement different prices sources for the recursivetree/seat-prices-core price provider system. If you are on SeAT 5 and use a plugin that uses recursivetree/seat-prices-core internally, you can install and use any of the following price provider packages.

Price Provider Version Description recursivetree/seat-prices-evepraisal Prices from evepraisal clones recursivetree/seat-prices-evemarketer Prices from evemarketer.com cryptatech/seat-prices-janice Prices from https://janice.e-351.com/ cryptatech/seat-prices-fuzzwork Prices from https://market.fuzzwork.co.uk/"},{"location":"community_packages/#library-packages","title":"Library Packages","text":"

These packages provide utilities for other packages and usually don't need to be installed manually.

Package Version Description warlof/seat-connector A generic connector module that handles invites and roles management with any registered platform recursivetree/seat-treelib A module that contains shared code for all recursivetree/* plugins recursivetree/seat-prices-core This plugin provides a price provider system for all plugins dealing with prices. Seat 5.x only."},{"location":"community_packages/#deprecated-packages","title":"Deprecated packages","text":"Package Version Description eve-scout/eveseat-oauth2-server This EVE SeAT package enables an OAuth2 server for Single sign-on. flyingferret/seat-whtools A small collection of tools for helping with Wh-Life corporation management, including calculating doctrine stocking levels (based on contracts and denngarr/seat-fitting plugin), a blue loot tax calculator, and a skill base certificate management. Currently very much a work in progress. freedenizen/eveseat-notes A notes addon for seat 1.x herpaderpaldent/seat-discourse SeAT Discourse enables SeAT to act as SSO provider for your Discourse-Forum instance. Groups and Categories do respect roles of members. With this package you can create hidden sections for your member and public sections for potential recruits to which members get automatically access to. Important: Check installation instructions on Github. herpaderpaldent/seat-groups Module to create auto, open and managed role groups to which user can be automatically be assigned, user can opt-in or user can apply to. herpaderpaldent/seat-notifications This is a fully functional notification package for discord and slack notifications. This package is very easily extendable by other packages and should replace core notifications at some point. Currently seat-groups provide many useful notifications. Notifications are send out by slack or discord bot and uses twice a full oAuth2 authentication of the user. warlof/seat-migrator A migration script between SeAT 2 and SeAT 3 warlof/seat-slack-sso Slack SSO integration for seat 2.x warlof/eveseat-mining-ledger ESI capability that provides a mining ledger to SeAT 2.x warlof/slackbot A slack bot that handles invites and kicks based on an api key"},{"location":"community_packages/#other-seat-related-packages","title":"Other SeAT related packages","text":"
  • nullsecurity-australia/helm-charts Allows to install EVE SeAT on a Kubernetes Cluster

Danger

Packages after this message are provided as history and idea database. They will not work on the stable version since they are non longer maintained by their author or have been integrated in core.

  • Betriebsrat/err-seat Seat Api Interface for errbot
  • eve-scout/passport-eveseat Passport strategy for authenticating with EVE SeAT using the OAuth 2.0 API.
  • eve-scout/nodebb-plugin-sso-eveseat This NodeBB plugin allows users login/register via their EVE SeAT account.
"},{"location":"community_packages/#installing-different-versions","title":"Installing different versions","text":"

Sometimes it can be useful to install a version different from the latest version, for example if you want to install an older version of a plugin or if you want to test a bugfix. The easiest way to find all available versions is to go to the packagist site of the plugin by clicking on the version in the available plugins list. On packagist, if you scroll down, to the right you will find a list of all available versions.

BladeDocker (SeAT 4.x)Docker (SeAT 5.x - using Traefik)Docker (SeAT 5.x - using proxy)

Follow the normal installation steps, but change the composer require command to include the package according to the following example:

sudo -H -u www-data bash -c 'composer require <package vendor>/<package-name>:<version-name>'\n

In your .env file, add the version to the package like this:

SEAT_PLUGINS=<vendor>/<package>:<version>,cryptaeve/seat-squad-sync:4.0.2\n
Next, restart the stack as usual.

docker-compose down\ndocker-compose up -d\n

In your .env file, add the version to the package like this:

SEAT_PLUGINS=<vendor>/<package>:<version>,cryptaeve/seat-squad-sync:4.0.2\n
Next, restart the stack as usual.

docker-compose down\ndocker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n

In your .env file, add the version to the package like this:

SEAT_PLUGINS=<vendor>/<package>:<version>,cryptaeve/seat-squad-sync:4.0.2\n
Next, restart the stack as usual.

docker-compose down\ndocker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n
"},{"location":"styling/","title":"Styling","text":""},{"location":"styling/#styling","title":"Styling","text":"

By default, SeAT uses Bootstrap 3 and the Admin LTE template.

You may want to customise SeAT design to match either your corporation or alliance colours.

To do so, you can use two available css hooks :

  • custom-layout-mini.css used by the sign-in page
  • custom-layout.css used by all the entier application, globally
"},{"location":"styling/#bare-metal-installs","title":"Bare Metal Installs","text":"

Both files must be located into your public directory.

Example

Using the default base directory, you'll get the following path : - /var/www/seat/public/custom-layout-mini.css - /var/www/seat/public/custom-layout.css

These files are loaded automatically if they are detected - you have nothing else to do to enable them.

"},{"location":"styling/#docker-installs","title":"Docker Installs","text":"

An example of adding these to your Web UI container is provided below:

Note

Do note the version in docker-compose.yml and reflect this in your override file otherwise version mismatches will occur.

  • Creating custom directory in /opt/seat-docker/ and add files to new directory
  • Creating docker-compose.override.yml in /opt/seat-docker/ directory
  • Adding following code to docker-compose.override.yml Note: Uncomment the needed file(s) by removing the #
SeAT 4SeAT 5 (using Traefik)SeAT 5 (using proxy) 
version: \"3.2\"\nservices:\nseat-web:\nvolumes:\n#      - /opt/seat-docker/custom/custom-layout-mini.css:/var/www/seat/public/custom-layout-mini.css\n#      - /opt/seat-docker/custom/custom-layout.css:/var/www/seat/public/custom-layout.css\n

Once you have placed the files you will need to run docker-compose up -d for it to take effect.

version: \"3.2\"\nservices:\nfront:\nvolumes:\n#      - /opt/seat-docker/custom/custom-layout-mini.css:/var/www/seat/public/custom-layout-mini.css\n#      - /opt/seat-docker/custom/custom-layout.css:/var/www/seat/public/custom-layout.css\n

Once you have placed the files you will need to run docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d for it to take effect.

version: \"3.2\"\nservices:\nfront:\nvolumes:\n#      - /opt/seat-docker/custom/custom-layout-mini.css:/var/www/seat/public/custom-layout-mini.css\n#      - /opt/seat-docker/custom/custom-layout.css:/var/www/seat/public/custom-layout.css\n

Once you have placed the files you will need to run docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d for it to take effect.

An example of a customized login page using custom-layout-mini.css would be:

Note

Valid corporations or alliances ids in the URL can be used for login.logo::before section.

/**\n * SeAT login page layout\n */\n@media all {\nhtml, body {\nheight: auto;\n}\n.login-page, .register.body {\ncolor: rgb(255,255,255);\nbackground-image: url(https://web.ccpgamescdn.com/aws/eveonline/sso/background.jpg);\nbackground-position: center center;\nbackground-repeat: no-repeat;\nbackground-size: cover;\nbackground-attachment: fixed;\n}\n.login-box, .register-box {\nwidth: 360px;\nmargin: 0;\nposition: absolute;\ntop: 50%;\nleft: 50%;\nbackground: rgba(48,48,48,.8);\ntransform: translate(-50%, -50%);\nborder: 5px solid #ecf0f1;\nborder-radius: 40px;\nbox-shadow: 0 1px 1px rgba(0,0,0,0.05);\n}\n.login-logo, .register-logo {\nfont-size: 35px;\ntext-align: center;\nmargin-bottom: 25px;\nfont-weight: 300;\nmargin-top: 50px;\n}\n.login-logo::before, .register-logo::before {\ncontent: \" \";\ndisplay: block;\nwidth: 128px;\nheight:128px;\nmargin: 0 auto;\nbackground-image: url(https://images.evetech.net/corporations/98482334/logo?size=128);\nborder-radius: 50%;\nmargin-bottom: 50px;\n}\n.login-box-body, .register-box-body {\nbackground: transparent;\npadding: 20px;\nborder-top: 0;\ncolor: inherit;\n}\n}\n

The above code will create the login page below:

"},{"location":"troubleshooting/","title":"Troubleshooting","text":""},{"location":"troubleshooting/#troubleshooting","title":"Troubleshooting","text":"

So the inevitable happened. Something broke or simply isn't working as expected! That's OK. Usually its possible to recover from almost any type of error. The only thing that you can't recover from is not making database backups!

There are a few things you can do to perform general troubleshooting. These range from flipping SeAT into debug mode to simply running a self diagnostics command. Lets take a look at a few steps you can take:

"},{"location":"troubleshooting/#whoops","title":"Whoops","text":"

Whoops, looks like something went wrong.

The dreaded \"Whoops\" message has appeared and now you need to figure out why. Normally, this means that something serious broke and the application simply can't recover by itself. In many cases it could either be a quick fix you can do yourself, or something that could result in the need to fix some code.

In either case, the next steps to perform when seeing this would be to either enable debug mode and reloading the page / request that failed, or by viewing the log file while retrying the failed request.

"},{"location":"troubleshooting/#memory-errors","title":"Memory Errors","text":"

Fatal error: Allowed memory size of #### bytes exhausted (tried to allocate 4096 bytes)...

If you are presented with an error below similar to this after \"Updating Dependencies\" you must append your .ENV file with COMPOSER_MEMORY_LIMIT= -1 and restart the stack with the following if you are using docker:

Docker (SeAT 4.x)Docker (SeAT 5.x - using Traefik)Docker (SeAT 5.x - using reverse proxy) 
docker-compose up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n

Note

Note: spacing is important for this parameter, if you are unsure copy/paste the needed line into your .ENV file.

"},{"location":"troubleshooting/#enabling-debug-mode","title":"Enabling Debug Mode","text":"

Debug mode controls how much information about an error condition is displayed to the user. When debug mode is enabled, the error message will be extremely verbose, whereas when its disabled, it simply states that an error had occurred. In either case, the error will always be written to the logs. By default, SeAT does not have debug mode enabled. There are many reasons for this with the primary reason being security related. It goes without saying that once you have completed debugging and fixing your instance, always make sure you disable debug mode afterwards.

Once you have enabled debug mode, any errors that may occur would look something like the following instead of the default \"Whoops\" message. Depending on if you have development packages installed (which you wouldn't by default in non-development installations), the debug page may look slightly different.

Irrespective of how you installed SeAT, enabling debug mode is always a matter of changing the APP_DEBUG configuration option in the .env to `true. However, for it to apply depends on how you installed, so follow the appropriate steps below.

"},{"location":"troubleshooting/#debug-mode-host-installs","title":"Debug Mode - Host Installs","text":"

Assuming you installed SeAT on your host using either the SeAT tool or manually, cd to your SeAT installation directory. If you followed the guides on this documentation website, that would be in /var/www/seat. Next, open the .env file in a text editor and modify the line that says APP_DEBUG=false to say APP_DEBUG=true.

The change would immediately take effect and you can simply reload the failed request for a detailed error message and code stack trace.

"},{"location":"troubleshooting/#debug-mode-docker-installs","title":"Debug Mode - Docker Installs","text":"

If you installed using Docker, cd to the directory where the docker-compose.yml file is located. Assuming you followed the guides on this website, that would be in /opt/seat-docker. Next, open the .env file in a text editor and modify the line that says APP_DEBUG=false to say APP_DEBUG=true.

For the change to take effect, you need to reload the stack:

Docker (SeAT 4.x)Docker (SeAT 5.x - using Traefik)Docker (SeAT 5.x - using reverse proxy) 
docker-compose up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n

The containers will take a few moments to settle down after which you can reload the failed the request for a detailed error message and code stack trace.

"},{"location":"troubleshooting/#checking-log-files","title":"Checking Log Files","text":"

Logs are always written to one of two log files irrespective of whether the application is in debug mode or not. Application logs go to the Laravel frameworks log files. API requests sent to ESI are stored int he Eseye log file. Logs are stored in the applications storage directory which can be found in the storage/logs folder.

Assuming you followed the guides on this documentation site, the full path to the directory where log files are will be /var/www/seat/storage/logs/. In the case of Docker installations, this will also be the path within the seat-web/front or seat-worker/worker container. Log files are rotated daily and are kept for a maximum of 10 days by default. Therefore, to get to todays application logs, the log file itself may be called laravel-2018-05-31.log. To find today's ESI requests logs, the log file will be called eseye-2018-05-31.log.

"},{"location":"troubleshooting/#live-logs-host-installs","title":"Live Logs - Host Installs","text":"

Irrespective of which log file you want to look at, getting todays live logs written to screen can be done with the following commands:

Application Logs:

tail -f /var/www/seat/storage/logs/laravel-$(date +%Y-%m-%d).log\n

Esye / ESI Logs:

tail -f /var/www/seat/storage/logs/eseye-$(date +%Y-%m-%d).log\n
"},{"location":"troubleshooting/#live-logs-docker-installs","title":"Live Logs - Docker Installs","text":"

Application source code and log files are shared between the seat-web/front, seat-worker/worker and seat-cron/scheduler containers. Therefore, the following commands can be executed on any of those containers. For purposes of demonstration, we are going to tail the logs from the seat-web/front container.

First, enter get a shell within the seat-web/front container while in the /opt/seat-docker/ directory with:

SeAT 4.xSeAT 5.x 
docker-compose exec seat-web sh\n
docker compose exec front sh\n

Next, tail the log files you want to see.

Application Logs:

tail -f /var/www/seat/storage/logs/laravel-$(date +%Y-%m-%d).log\n

Esye / ESI Logs:

tail -f /var/www/seat/storage/logs/eseye-$(date +%Y-%m-%d).log\n
"},{"location":"troubleshooting/#diagnose-command","title":"Diagnose command","text":"

A diagnostics command exists that aims to perform a number of self-checks to help you diagnose problems. This command should be run as the same user the SeAT workers are running as, which is typically either www-data on Ubuntu / Debian based systems and nginx on CentOS based systems. If you have created yourself a separate user for SeAT, then running the diagnose command as that user is what you need to do.

"},{"location":"troubleshooting/#diagnose-host-installs","title":"Diagnose - Host Installs","text":"

Host installs require you to first cd to the directory where you installed SeAT. If you followed the guides on this website, that would be /var/www/seat. Next, run the diagnose command as the user you are running the workers as. If you are the root user, you can run it with:

su -c 'php artisan seat:admin:diagnose' -s /bin/sh www-data\n
"},{"location":"troubleshooting/#diagnose-docker-installs","title":"Diagnose - Docker Installs","text":"

For Docker installations, the only requirement to run the diagnose command would be to ensure that you are currently in the same folder as that where the stacks docker-compose.yml file lives. If you followed the guides on this website that would be in /opt/seat-docker. Next, run the command with:

SeAT 4.xSeAT 5.x 
docker-compose exec seat-web su -c 'php artisan seat:admin:diagnose' -s /bin/sh www-data\n
docker compose exec front su -c 'php artisan seat:admin:diagnose' -s /bin/sh www-data\n
"},{"location":"about/contact/","title":"Contact","text":""},{"location":"about/contact/#contact","title":"Contact","text":"

Have a question? Want to say thank you? Need to express your opinion on SeAT? You are welcome to join us on our official Discord Server! https://discord.gg/VcUZRcnMYK.

"},{"location":"about/contact/#eve-online-forum-thread","title":"EVE Online Forum Thread","text":"

Track the conversation on the EVE Online Forums.

"},{"location":"about/reporting_bugs/","title":"Reporting Bugs","text":""},{"location":"about/reporting_bugs/#reporting-bugs","title":"Reporting Bugs","text":"

So, you think its time to report an issue. Awesome! However, before you do this, please go through the troubleshooting steps first to identify any common errors that you might be able to to fix yourself.

"},{"location":"about/reporting_bugs/#the-more-info-the-better","title":"The more info, the better","text":"

In order to best understand the bug, we need as much info as possible about your environment. For that, you can run the following command (from your SeAT directory), and copy / paste the output as part of your bug report:

php artisan seat:admin:diagnose\n
"},{"location":"about/reporting_bugs/#log-files","title":"Log files","text":"

Log files are a fantastic resource. Check out the Laravel log for any Exception type errors, and add them to your bug report. The log file is located (relative to where you installed SeAT) at:

storage/logs/laravel-<todays-date>.log\n
"},{"location":"about/reporting_bugs/#screenshots-and-debug-mode","title":"Screenshots and debug mode","text":"

Screenshots may also help, so don't be shy to take some and attach them to your bug report! If you flip your installation into debug mode then it may be possible to capture the error that is occurring via a screenshot.

"},{"location":"about/reporting_bugs/#report-the-bug","title":"Report the bug","text":"

Finally, to report the bug, head over to Github Issues and click on New Issue.

"},{"location":"admin_guides/admin_login/","title":"Admin Login","text":""},{"location":"admin_guides/admin_login/#admin-login","title":"Admin Login","text":"

SeAT is heavily relaying on EVE Online Single Sign-On to authenticate user. However, it's also shipped with a built-in administrator user.

You need an admin account in order to do certain tasks like configuring your instances, roles, squads, etc...

In order to authenticate with built-in admin user, use command disclosed bellow (choose your context).

Docker (SeAT 4.x)Docker (SeAT 5.x)Bare metal 
cd /opt/seat-docker\ndocker-compose exec seat-web php artisan seat:admin:login\n
cd /opt/seat-docker\ndocker compose exec front php artisan seat:admin:login\n
sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:admin:login'\n

You'll get a link after the command has finished running, which looks similar to the one bellow:

SeAT Admin Login URL Generator\nUser 'admin' does not exist. It will be created.\nChecking if 'admin' is a super user\nAdding 'admin' to the Superuser role\nGenerating authentication token\n\nYour authentication URL is valid for 60 seconds.\nhttp://localhost/auth/login/admin/9G3sb8hjMvrbIJrIf10KKtIj1c8e9mL5\n

Copy it and paste it inside your browser, and you will be authenticated as the built-in admin account.

Hint

You can define a standard user account as an administrator from the user card. To do so, go into Settings > Users, search the user which need to be upgraded and clic on the edit button. On the displaying card, check Administrator and confirm change using edit button.

Warning

If you have not configured the APP_URL setting in the .env file, then the admin url will be generated for localhost. This is most likely incorrect and you can simply replace localhost with your server IP address or domain name.

"},{"location":"admin_guides/authorizations/","title":"Authorizations","text":""},{"location":"admin_guides/authorizations/#role-based-access-control","title":"Role-Based Access Control","text":""},{"location":"admin_guides/authorizations/#introduction","title":"Introduction","text":"

SeAT supports configuring user access control by means of Role-based Access Control (RBAC). This allows for SeAT administrators to granularly control who has access to what based on which roles a SeAT user has.

In SeAT, the default rule is to deny access. As a result, someone without a permission will not be able to access the requested resource.

Tip

Use roles to define permission without wondering about automation. You will be able to set up role auto assignment with Squads. The more granular are your roles, the easier they will be to maintain them and built your automation rules.

"},{"location":"admin_guides/authorizations/#definitions","title":"Definitions","text":"

This section aims to clear up the definitions used in the SeAT RBAC implementation.

  • User A SeAT user account. This can be either a user account that was created in SeAT itself, or an automatically created account based on SSO. The only difference between the accounts is that with an SSO account, SeAT has no idea what the account's password is. Otherwise, everything else is exactly the same.

  • Scope A scope is a domain grouping different permissions related to the same topic. Permissions from certain scope can be limited (ie: character or corporation).

  • Permission A Permission is an attribute that is assigned to a Role. It grants access based on the specific permission.

  • Role A Role is simply a collection of permissions. Users get assigned a roles and inherit the permissions granted by that role. A user cannot be given a raw permission. Permissions can only be granted by creating a Role, assigning permissions to the Role and granting the role to a user.

  • Filters Permissions from certain scope can received filters. That simply mean the granted permission is limited to certain conditions. As an example, you may want to limit the asset permission from character scope to only a selection of character.

  • Entity An entity is something on which the permission will be applied. It can be a Character, a Corporation or anything else.

"},{"location":"admin_guides/authorizations/#interface","title":"Interface","text":"

To manage roles, you must go into Settings from SeAT sidebar, then choose Access Management.

Info

To be able to manage SeAT roles, you must be authenticated as an administrator user. Administrators can be managed in the users list, located in Settings.

"},{"location":"admin_guides/authorizations/#role-card","title":"Role card","text":"

The Role card is compounds of two main area.

Left pane contains basic information. It allows you to provide a name, a description and upload an optional logo. Those information can be sync with any third party platform using the API.

Tip

Provided logo are stored into database - so you don't need to worry when moving your installation.

Right pane contains role settings. The pane is split in two tabs - first tab is showing the role permissions definitions. Second pane, the members one, gives you the current role members and related management actions.

"},{"location":"admin_guides/authorizations/#role-definition","title":"Role definition","text":""},{"location":"admin_guides/authorizations/#role-permissions","title":"Role permissions","text":"

The role permissions tab is built using a navigation bar, which is showing all available scopes - and the list of permissions from active scope. Use the scope navigation to show permissions related to each scope.

Each permission block is structured as follow:

  • a checkbox: if you check it, you mark the permission to be granted by the role
  • an optional icon: it is visual only and help to pair some permission inside a same scope. It might be useful for large scope like character or corporation to distinguish permission kind. Options include military, financial and industrial.
  • a user friendly name
  • an optional description: this is mostly a text explaining the permission purpose
  • an optional limits button: it will help you to filter/restrict the permission to only a certain population. Only character and corporation scope permissions can be filtered.

Warning

In SeAT 3, leaving the affiliations of a role empty, meant that the role would apply to no relevant entities. It had no effect. This has changed in SeAT 4. If you give a role a permission with no filter, this permission will apply globally to all entities. For example giving the Corporation Sheet permission to a role with no filter means that the members of the role will be able to see the corporation sheets of every corporation on the server.

"},{"location":"admin_guides/authorizations/#role-members","title":"Role members","text":"

The role members tab is a table listing all users who are currently assigned the role. All of them receive the benefits of the permissions which have been defined in the permissions tab from that same role. You will be able to add or remove any user to or from the role using action buttons.

To remove an user from the role to which is part, simply click on the \"Remove\" button located on the member line.

To add one or multiple user to the role, use the green \"Add\" button located at bottom right corner. This will show you a dialog box. Use the drop-down control to find users which you want to add. Once all users to be add have been chosen, click on the \"Close\" button located at bottom right corner from that modal. Selected users will be shown with a warning background to highlight their addition to the role. This means their selection isn't saved yet - you have to apply change using the green \"Submit\" button located under the General pane.

"},{"location":"admin_guides/buckets/","title":"Buckets","text":""},{"location":"admin_guides/buckets/#buckets-and-continuous-update","title":"Buckets and continuous update","text":"

Starting with eveseat/console@4.7.0 and eveseat/eveapi@4.8.0, a new system has been designed to ensure continuous updates and reduce load on both SeAT stack and ESI.

"},{"location":"admin_guides/buckets/#general","title":"General","text":"

Each instance is allowed to get up to 30 buckets. Every bucket will handle a batch of tokens, and their related characters and corporations data update. Size of bucket is dynamically set based on the following criteria :

  • a token can be updated only once every 3600 seconds
  • a token can be updated in an average of 120 seconds

Info

Most data ESI endpoint and data they deliver are restricted to a 1-hour cache long. However, certain are shorter and benefit of dedicated command to allow you update more frequently - please, do not abuse of them.

  • esi:update:contracts
  • esi:update:killmails
  • esi:update:affiliations
  • esi:update:notifications
"},{"location":"admin_guides/buckets/#health","title":"Health","text":"

You can determine a bucket status using seat:buckets:list and seat:buckets:info ID commands. The first one will show you all existing buckets in the system together with the amount of token they're managing and their status. The second will show you details about a specific bucket including characters they have the charge of.

A bucket can have one of the following status :

  • available : there are free slots according to current threshold
  • balanced : maximum tokens has been reached according to the current threshold, and the bucket cannot handle more token
  • overload : there are too many tokens handled by this bucket according to the current threshold
"},{"location":"admin_guides/buckets/#balancing","title":"Balancing","text":"

Bucket balancing is run every time a token is created or removed from the system. As a result, you may find bucket with a certain amount of token at one time and a completely different one at another.

If you find yourself with unbalanced buckets, you can force them to be balanced using seat:buckets:balance. However, depending on instance state, certain buckets will not be able to be more balanced for a time (ie: lack of tokens).

"},{"location":"admin_guides/buckets/#update","title":"Update","text":"

This system has been designed to ensure there is a bucket to update every two minutes (except for instances with less than 30 tokens). You can force bucket to be processed and bypass the scheduler using seat:buckets:update - however, keep in mind that tokens handled by updating bucket will be frozen for the next 60 minutes.

Hint

Manual command to force update character and corporation are still available. They require the ID of a tied character.

  • esi:update:characters character_id
  • esi:update:corporations character_id
"},{"location":"admin_guides/docker_admin/","title":"Docker Admin","text":""},{"location":"admin_guides/docker_admin/#docker-administration","title":"Docker Administration","text":"

Occasionally you will need to perform administrative tasks in your SeAT instance running within docker. Be it because you would like to configure TLS for the web interface, change the port of the SeAT webserver or simply generate an admin login URL, this guide aims to help you get familiar for the commands needed for this.

Many of the commands are exactly the same as those used in a bare metal installation, except for the fact that they are always prefixed with docker compose and run from the same directory that you have the seat docker-compose.yml file stored. If your docker-compose.yml lives in /opt/seat-docker, you will need to cd to that directory first and then execute the docker compose commands.

Info

With SeAT 5, we migrated from the docker-compose command to docker compose. Besides the name, they are fully compatible. If you are still on SeAT 4, you have to use docker-compose instead of docker compose for all actions. This applies to all actions, not just the ones listed on this page.

"},{"location":"admin_guides/docker_admin/#container-status","title":"Container Status","text":"

For a quick, birds-eye view on the status of the containers within the SeAT docker stack, the following command may be run:

SeAT 4.xSeAT 5.x 
docker-compose ps\n
docker compose ps\n

This should give you the name, entry point, current status and internal ports used within the docker network as output.

"},{"location":"admin_guides/docker_admin/#configuration-changes","title":"Configuration Changes","text":"

A dockerized installation of SeAT is primarily configured via a configuration file located at .env. Configuration options such as your applications SSO secrets, SeAT's web server ports are amongst the many configuration options available in this file.

Making changes to this file requires the docker stack to be restarted so that the configuration may be applies. An example case would be when you configure SSO for your instance.

Once you have made a configuration change, save the .env file and restart the stack by simply running the following command from the path where the docker-compose.yml lives:

Docker (SeAT 4.x)Docker (SeAT 5.x - using Traefik)Docker (SeAT 5.x - using reverse proxy) 
docker-compose up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n
"},{"location":"admin_guides/docker_admin/#live-container-logs","title":"Live Container Logs","text":"

Getting an idea of what is happening inside of the containers may be useful for many things, including debugging any issues that may occur. All of the containers generate logs that can be viewed either in isolation, or all of the containers in the stack.

Docker (SeAT 4.x)Docker (SeAT 5.x)

To view a single services' logs (seat-web in this examples case), run:

docker-compose logs --tail 10 -f seat-web\n

All services can referenced by their name using docker compose. You can see the service names here. At the time of writing this doc, the available services were: mariadb, redis, traefik, seat-web, seat-worker and seat-cron.

To view a single services' logs (front in this examples case), run:

docker compose logs --tail 10 -f front\n

All services can referenced by their name using docker compose. You can see the service names here and in the adjacent docker-compose.x.yml files. At the time of writing this doc, the available services were: mariadb, cache, traefik, front, worker and scheduler.

To view all service logs at once, run:

Docker (SeAT 4.x)Docker (SeAT 5.x) 
docker-compose logs --tail 10 -f\n
docker compose logs --tail 10 -f\n

Once you are done viewing the output, simply pressing ^C will exit the log viewer.

"},{"location":"admin_guides/docker_admin/#application-logs","title":"Application Logs","text":"

While most processes will output information to stdout (which is what you will see when you run docker-compose logs), there are some app specific logs also generated.

"},{"location":"admin_guides/docker_admin/#logs-web-ui","title":"Logs - Web UI","text":"Docker (SeAT 4.x)Docker (SeAT 5.x)

If you are getting HTTP 500's, or other exception when using the web interface, the best place to find the relevant logs will be in the seat-web service, in the /var/www/seat/storage/logs directory. To reach them, run docker-compose exec seat-web bash. This will drop you into bash shell in the container:

$ docker-compose exec seat-web bash\nroot@9aff5b002ca0:/var/www/seat#\n

If you are getting HTTP 500's, or other exception when using the web interface, the best place to find the relevant logs will be in the front service, in the /var/www/seat/storage/logs directory. To reach them, run docker-compose exec front bash. This will drop you into bash shell in the container:

$ docker-compose exec front bash\nroot@9aff5b002ca0:/var/www/seat#\n

Next, cd to the logs directory with:

cd storage/logs/\n

This directory should have daily log files for you to view.

"},{"location":"admin_guides/docker_admin/#logs-worker-updaters","title":"Logs - Worker / Updaters","text":"Docker (SeAT 4.x)Docker (SeAT 5.x)

If you think your workers may be causing some exceptions, or you want to investigate why they may be failing, you can do so in the seat-worker service. Just like for the web UI, get a bash shell and cd to the logs directory.

# docker-compose exec seat-worker bash\nroot@8ed8967348f1:/var/www/seat# cd storage/logs/\nroot@8ed8967348f1:/var/www/seat/storage/logs# ls\neseye-2020-08-23.log\n

If you think your workers may be causing some exceptions, or you want to investigate why they may be failing, you can do so in the worker service. Just like for the web UI, get a bash shell and cd to the logs directory.

# docker compose exec worker bash\nroot@8ed8967348f1:/var/www/seat# cd storage/logs/\nroot@8ed8967348f1:/var/www/seat/storage/logs# ls\neseye-2020-08-23.log\n

The eseye log as well as Laravel log should help you debug what is going on.

"},{"location":"admin_guides/docker_admin/#installing-plugins","title":"Installing Plugins","text":"

SeAT provides the ability for third party developers to integrate with the core environment to extend its features and functionality. It is possible to install those plugins in a docker environment. Installing a plugin is relatively easy too. All you need to do is add the plugin name to your SEAT_PLUGINS variable in the .env file and run docker-compose up -d again. The plugin will be read from the .env file and installed as the application container starts.

For example. Open the .env file (which is most probably at /opt/seat-docker/.env) and edit the SEAT_PLUGINS variable to include the package you want to install. In our example we use the pseudo package called user/seat-plugin:

# SeAT Plugins\n# This is a list of the all of the third party plugins that you\n# would like to install as part of SeAT. Package names should be\n# comma separated if multiple packages should be installed.\nSEAT_PLUGINS=user/seat-plugin\n

Save your .env file and run docker-compose up -d to restart the stack with the new plugins as part of it. Depending on how big the plugin itself may be, this could take a few moments to complete.

You can monitor the installation process by running:

Docker (SeAT 4.x)Docker (SeAT 5.x) 
docker-compose logs --tail 10 -f\n
docker compose logs --tail 10 -f\n
"},{"location":"admin_guides/docker_admin/#database-backups-and-restore","title":"Database Backups and Restore","text":"

Backups. They are important and really simple to do. To perform a backup of the current database used within the docker stack, compressing and saving it to a file called seat_backup.sql.gz, run:

Docker (SeAT 4.x)Docker (SeAT 5.x) 
docker-compose exec mariadb sh -c 'exec mysqldump \"$MYSQL_DATABASE\" -u\"$MYSQL_USER\" -p\"$MYSQL_PASSWORD\"' | gzip > seat_backup.sql.gz\n
docker compose exec mariadb sh -c 'exec mysqldump \"$MYSQL_DATABASE\" -u\"$MYSQL_USER\" -p\"$MYSQL_PASSWORD\"' | gzip > seat_backup.sql.gz\n

To restore a backup to a new dockerized instance of SeAT, run:

Docker (SeAT 4.x)Docker (SeAT 5.x) 
zcat seat_backup.sql.gz | docker-compose exec -T mariadb sh -c 'exec mysql \"$MYSQL_DATABASE\" -u\"$MYSQL_USER\" -p\"$MYSQL_PASSWORD\"'\n
zcat seat_backup.sql.gz | docker compose exec -T mariadb sh -c 'exec mysql \"$MYSQL_DATABASE\" -u\"$MYSQL_USER\" -p\"$MYSQL_PASSWORD\"'\n
"},{"location":"admin_guides/scaled_deployments/","title":"Scaled Deployments","text":"

DEPRECATED!!!

This guide is deprecated and is not functional in SeAT v3. If you need more performance in SeAT v3 then you have two options, move the DB alone to another server, and/or beef up the server SeAT is running on. This guide may be updated in the future when horizontal scaling is viable again. It is left as is for now due to academic and nostalgic reasons.

"},{"location":"admin_guides/scaled_deployments/#scaled-seat-deployments","title":"Scaled SeAT Deployments","text":"

At some stage, you may come to a point where a single install of SeAT might not be enough to process api key updates. Thankfully, it is actually very easy to scale SeAT horizontally in order to improve performance. This document aims to share some need to knows before embarking on a tiered installation of SeAT.

"},{"location":"admin_guides/scaled_deployments/#definitions","title":"Definitions","text":"

Lets get some definitions cleared up.

"},{"location":"admin_guides/scaled_deployments/#server","title":"Server","text":"

A server is defined as any VPS, hardware, docker container, or other form of virtualization. When talking performance though, keep in mind that there will probably be very little performance gains when everything runs on the same physical hardware instance.

"},{"location":"admin_guides/scaled_deployments/#seat-component","title":"SeAT component","text":"

A SeAT Component is a collection of SeAT packages and configurations that is responsible for performing a specific task. Tasks include the SeAT Web Interface, the job workers or dispatchers.

"},{"location":"admin_guides/scaled_deployments/#components","title":"Components","text":"

Before we can talk scale, we need to understand which components SeAT actually consists of. We will not talk about the immutable resources here as they will be mentioned in the next section.

So, which components are there to SeAT?

  • The web front end.
  • The queue workers.
  • The job dispatcher.

Each of these components can live on their own server and must share the same immutable resources.

"},{"location":"admin_guides/scaled_deployments/#immutable-resources","title":"Immutable resources","text":"

While almost every component in SeAT can 'run on its own', there are some services that SeAT consumes that SeAT can not scale itself. Instead, SeAT can consume a clustered or load balanced instance of these services. There are various reasons for this where the most important is that state is maintained between queue workers using Redis and MariaDB.

Services that should be shared between all SeAT components are:

  • The Redis cache.
  • The MariaDB database.

When mentioning these components, they can definitely exist in their clustered/load balanced forms. For Redis, have a look at their Redis cluster tutorial and for MariaDB, you can have a look at their MariaDB cluster installation.

"},{"location":"admin_guides/scaled_deployments/#simple-scaled-setup","title":"Simple scaled setup","text":"

The following example setup is probably the most simple option to gain performance improvements by scaling out. The gist of it is that we simply add more queue worker components to the SeAT setup.

Lets start by taking a look at a diagram, showing the extra queue worker component added.

Installing a new server with only the queue worker component setup can bring a significant speed boost into the environment. A new queue worker could be configured to run an extra 4-6 jobs. This queue worker must be configured to make use of the immutable resources.

"},{"location":"admin_guides/scaled_deployments/#more-complicated-scaled-setup","title":"More complicated scaled setup","text":"

Of course, one can totally go full nelson and explode all of the components in use. Below is an example deployment (with data flow links, red for redis, blue for MariaDB) that shows how each SeAT component can live on its own server.

"},{"location":"admin_guides/scaled_deployments/#component-setups","title":"Component setups","text":"

Lets talk about component configurations quickly. Apart from the immutable resources, all of the software needed can be sourced from SeAT packages. All of the standard requirements such as PHP7.1 and Supervisor 3 also apply. However, not all components would need a web server for example.

Below are the descriptions (and short requirements list) for the different SeAT components.

"},{"location":"admin_guides/scaled_deployments/#web-front-end","title":"Web front end","text":"

To setup a web front end component, use the following steps:

  • Ensure you have at least PHP7.1 installed.
  • Ensure that you have a web server installed that can serve the public/ directory from the SeAT project.
  • Ensure that you have composer installed and available in PATH.
  • Download SeAT somewhere like /var/www/seat using composer create-project eveseat/seat /var/www/seat --no-dev.
  • Once installed, configure the .env files database and Redis settings to connect to your immutable sources.
"},{"location":"admin_guides/scaled_deployments/#queue-worker","title":"Queue worker","text":"

To setup a queue worker component, use the following steps:

  • Ensure you have at least PHP7.1 installed.
  • Ensure that you have supervisor3 installed.
  • Ensure that you have composer installed and available in PATH.
  • Download SeAT somewhere using composer create-project eveseat/seat --no-dev.
  • Once installed, configure the .env files database and Redis settings to connect to your immutable sources.
  • Configure the workers in a seat.ini file for supervisor to start.
"},{"location":"admin_guides/scaled_deployments/#job-dispatcher","title":"Job dispatcher","text":"

To setup a job dispatcher component, use the following steps:

  • Ensure you have at least PHP7.1 installed.
  • Ensure that you have composer installed and available in PATH.
  • Download SeAT somewhere like /var/www/seat using composer create-project eveseat/seat /var/www/seat --no-dev.
  • Once installed, configure the .env files database and Redis settings to connect to your immutable sources.
  • Setup the cronjob to run php artisan schedule:run 1>> /dev/null 2>&1 every minute.
"},{"location":"admin_guides/squads/","title":"Squads","text":""},{"location":"admin_guides/squads/#squads","title":"Squads","text":""},{"location":"admin_guides/squads/#introduction","title":"Introduction","text":"

Since SeAT 4.0, there is a way to apply automatic logic between an end user and its roles. The purpose is to keep distinct the security and automations.

Squads is the core implementation of the deprecated seat-groups plugin.

"},{"location":"admin_guides/squads/#squads-types","title":"Squads Types","text":"

There are multiple kinds of squad. The way they work and the automations they apply depend on their type.

"},{"location":"admin_guides/squads/#automatic","title":"Automatic","text":"

This is the simplest squad type. Membership of a squad of this type is controlled by the filters (see below) set for the squad.

A member of an automatic squad cannot remove themselves from the group. If a user no longer fulfils the criteria of the filter set for the squad they will be automatically removed from it.

"},{"location":"admin_guides/squads/#manual","title":"Manual","text":"

Manual squads have to be applied to, the processing of the application depends on whether there is a moderator for the group or not.

If there is no moderator the application will be automatically accepted.

If there is at least one moderator they can accept or reject applications.

Filters applied to a squad of this type will have two effects: - hide the \"Apply\" button if the filter criteria are not met - kick the member from the group if the filter criteria are not met

"},{"location":"admin_guides/squads/#hidden","title":"Hidden","text":"

Hidden squads are visible exclusively to their members and admins. To be part of a hidden squad, the user needs to be added to it by an admin.

This mean, only admin user can invite another user to a hidden squad.

"},{"location":"admin_guides/squads/#squads-filters","title":"Squads Filters","text":"

Filters have different behaviors depending on the Squad Type. In case the Squad is of auto type, filters will be applied continuously to invite and kick members from the Squad - based on user changes.

Otherwise, filters are used to automatically kick members from a Squad and determine the availability of the \"Apply\" button on Squad Card.

Squads Filters have been designed to assist you to build rules which will determine whether a given user is eligible for a Squad. You pair different conditions together and link them with match keywords.

Match keywords can be either All or Any. All mean all conditions must be met by the user for them to be eligible. Any means that a user is eligible if they meet any of the conditions.

To add a condition, use Add Rule button located at the end of the modal. In case you have to build a complex rule, use Add Group which will allow you to pair multiple conditions in a single rule.

Info

Filters come with multiple operators. Not all operators work with all filters. Is and Is not are used to indicate either equality with criteria or inequality. Those operators are the most common and work with nearly all filter types. Contains is used to indicate that criteria must be included in a domain. This operator currently only works with the Scopes filter.

Example

In the example above, we want only users who own at least one character (inside either Get Off My Lawn OR Toilet Paper. alliances) AND with skill Capital Ships to be eligible for membership in our Squad.

"},{"location":"admin_guides/squads/#squad-applications","title":"Squad Applications","text":"

Applications are only available to manual squads.

For a user to be able to apply to a manual squad they need to meed the squads filter criteria. Otherwise, application button will not be available.

If the user applies to a moderated squad, they are required to fill an application form. This will leave you the ability to build workflow internally and allow moderators to check any incoming members. Users can also cancel squad applications at any time using the Cancel button which will replace the Join button.

"},{"location":"admin_guides/squads/#squad-moderators","title":"Squad Moderators","text":"

Moderators of a Squad don't need to be part of that squad. They will be able to see a list of every member of each squad they moderate, allowing them to invite further members or kick existing ones.

Squad moderators can also see Squad candidates, the time when they applied and each application form. From there, they can approve an application or reject it.

When an application is approved, the user who sent it is becomes a member of the Squad. If an application is denied, the application is removed and user can submit a new application.

Only administrator users can add or remove moderators to/from a Squad.

"},{"location":"admin_guides/squads/#interface","title":"Interface","text":""},{"location":"admin_guides/squads/#squads-list","title":"Squads List","text":"

Squads list is the entry point of squads. You can create a new squad, search for a squad, show available squads and get squad status from there. The Squads list is available to all users, without any restriction. You can access it using Squads from the left sidebar.

The list is split in three main areas. First area, at top, contains controls which will allow you to create a squad, or filter the shown squads. The main area, contains squads tiles from the active page. You can get up to six squads per page. Footer area is the pagination controls - allowing you to switch displayed page (first, previous, current, next and last).

Every Squad Tile is built following the same pattern :

1) Logo 2) Name and description 3) User status related to that squad 4) Metadata 5) Type

Except metadata, other attributes are self-explained. Metadata is a list of counters showing you, from left to right:

  • number of members of the squad (in white)
  • number of moderators of the squad (in orange)
  • number of applicants to the squad (in blue)

Hint

Squad Logo is a visual way for your end user to identify quickly a Squad. By default, logo are generated based on the Squad Name - but you can customise it in the Squad settings.

"},{"location":"admin_guides/squads/#squads-card","title":"Squads Card","text":"

When you click on a Squad Tile, you'll land on the related Squad Card. Squad Card is the landing area of a Squad. You will retrieve summarised information you had on the tile in the general pane.

In case the Squad is manual, you will get access to the list of Squad moderators. This list is public, this mean everyone can see it, without consideration if he's or not a member of that Squad.

Under the general pane, you'll get access to the list of roles assigned by the Squad. This list is disclosed to admin user only. This mean neither \"standard user\" or moderators will get access to it.

From that pane, you are able to remove a role from the squad or add other ones to it.

Members pane is visible to all moderators and squad members. Moderators can invite or kick user from the squad using actions buttons.

Info

When an user is kicked or invited from/to a Squad, the event is shown into security logs. You will be able to see who kick or invite any user from/to any Squad.

Last but not least, there is an extra Candidates pane which is available on Manual Moderated Squad. Squad applications can be managed from this area.

"},{"location":"admin_guides/squads/#squads-settings","title":"Squads Settings","text":"

When you create a new Squad, you have to fill a small form which will define it. Mandatory elements are :

  • The name of created squad which have to be unique
  • Squad Type (between Auto, Hidden and Manual - see Squads Types)
  • A description, which will be displayed on both Squad Card and Squad Tile

You also can upload a shiny logo which will be used instead the generated icon and provide filters for squad eligibility.

Caution

As soon as you save your Squad, filters are applied. In case the Squad is of auto type, eligible members will be added to it. For any other Squad Types, non-eligible members will be kicked from the Squad

Hint

Don't pay attention to your Squads Description. If it's too long, it will be shortened when displayed on the Squad Tile. However, the full description will always be available on the Squad Card into the general pane.

"},{"location":"admin_guides/understanding_tracking/","title":"Understanding Tracking","text":""},{"location":"admin_guides/understanding_tracking/#understanding-tracking","title":"Understanding Tracking","text":""},{"location":"admin_guides/understanding_tracking/#introduction","title":"Introduction","text":"

SeAT implements the Google Analytics Measurement Protocol. This document aims to explain in as much detail as possible how it has been implemented in SeAT, as well as what is tracked and what is not. This document aims to be as transparent as possible.

"},{"location":"admin_guides/understanding_tracking/#why","title":"Why","text":"

Well, the most obvious is it being nice to know how much SeAT is actually being used. One may argue that Github & packagist gives statistics on how many times the project has been installed / cloned, but that does not really reflect how many actual active installations there are.

Knowing how many active installs there are, encourages development.

Lastly, certain exception types are also sent as hits. This helps immensely with figuring out if a new version may have a serious bug.

"},{"location":"admin_guides/understanding_tracking/#how-its-implemented","title":"How its implemented","text":"

First of all, the Google Analytics Measurement Protocol is really just that. It just measures usage. In summary, when certain events happen, only a hit with what happened is sent. No other data is sent with the hit.

For example. When the scheduler queues jobs, a hit is sent that says that this happened, and that it happened for x amount of keys. This can be seen in the following line of code: QueueKeys. It can also be seen that no other data goes along with the hit. For example, the access_token and refresh_token (which is what most will be worried about) does not go with the hit.

Once a hit is getting ready to be sent, information such as which OS/Version as well as versions of installed SeAT packages gets sent along with the hit. This can be seen in the following lines of code.

"},{"location":"admin_guides/understanding_tracking/#how-are-you-protecting-my-privacy","title":"How are you protecting my privacy?","text":"

Very special care has been taken to ensure that no personally identifiable information goes along with the Measurement Protocol hits. In fact, its actually not allowed and serves no purpose for tracking. That being said, the following actions have been taken to ensure that privacy is key:

  • Source IP addresses are anonymized (Ref: eveseat/services:Jobs/Analytics#L132)
  • Only OS Name, Machine Type and Version is reported. Type a is specifically not sent as it will disclose the hostname of the server (Ref: eveseat/services:Jobs/Analytics#L151-L153)
  • Identifying an installation is done by generating a completely random V4 UUID. It is simply not possible to identify anyone with just this string (Ref: eveseat/services:Jobs/Analytics#L84-L90)
  • If you insist, tracking can be completely disabled in the SeAT web interface (Ref: eveseat/services:Jobs/Analytics#L213-L214 and eveseat/web:Http/Controllers/Configuration/SeatController#L66)
"},{"location":"admin_guides/understanding_tracking/#can-you-link-the-commits-where-this-was-added","title":"Can you link the commits where this was added?","text":"

Sure!

  • b2765c6d
  • f3f44dc6
  • cfdf20c0
  • ccd332de
  • b4a80803
"},{"location":"admin_guides/understanding_tracking/#are-the-stats-a-secret","title":"Are the stats a secret?","text":"

Not at all. However, as a start I am going to limit access to people whom have actively contributed towards SeAT. If you would like access, please ping me on Slack.

"},{"location":"admin_guides/understanding_tracking/#how-do-i-disable-this-crap","title":"How do I disable this crap?","text":"

If you insist on disabling the usage tracking, you can do this (as a SeAT administrator) by browsing to Configuration -> SeAT Settings and setting Allow Tracking to No.

"},{"location":"configuration/configuration_overload/","title":"Configuration Overload","text":"

This page aims to give a brief overview of how configuration is handled in SeAT and its packages. To give some perspective, we have to have a quick look at how packages are built and bootstrapped.

"},{"location":"configuration/configuration_overload/#quick-n-dirty-package-summary","title":"Quick-n-dirty-package summary","text":"

All of SeAT's core internals are built as packages. This means, every package has a service provider. All a service provider really is, is a class with 2 methods ie: handle() and register(). When a service provider is bootstrapped into the application, these 2 methods are called at some stage.

It is in these methods that we tell the Laravel framework more about our package. Amongst many things that we can tell it, one of them is configuration related. All we really telling the application is where the configuration file is, and under which namespace does it live. Another important fact is that SeAT package configurations are added with the mergeConfigFrom() method. This means, you can override the defaults in your installation without worrying about breaking the package itself.

"},{"location":"configuration/configuration_overload/#overriding-configuration","title":"Overriding configuration","text":"

Lets take a look at a sample package configuration file: The eveseat/eveapi package for example. At the time of this writing, it has 5 configuration options. The first being a version, the last being eseye_loglevel. When this package is installed, this configuration file will live somewhere deep inside your vendor folder. Changing the value there is not impossible, but it will be lost with the next package upgrade. The better method will be to override the change locally, inside you config/ folder here.

"},{"location":"configuration/configuration_overload/#an-example-changing-eseye_loglevel","title":"An example, changing eseye_loglevel","text":"

To start, create the file eveapi.config.php inside the config folder. Next, we add the contents in the file to return an array, specifying the eseye_loglevel key and its new value. The file would look something like this:

<?php\n// File: config/eveapi.config.php\nreturn [\n'eseye_loglevel' => 'debug',\n];\n

That's it. The configuration should now have been overridden.

"},{"location":"configuration/env_file_reference/","title":"Env File Reference","text":""},{"location":"configuration/env_file_reference/#env-reference","title":"Env Reference","text":"

In both the case of a Docker installation as well as a host based installation (manual or via SeAT tool), SeAT has some configuration values that can be set via an .env file. Depending on your installation type, this file will be in either /opt/seat-docker/.env or in /var/www/seat/.env

"},{"location":"configuration/env_file_reference/#configuration-value-reference","title":"Configuration Value Reference","text":"Parameter Name Default value Description APP_URL http://seat.local This is the public address where SeAT instance is reachable. That should match with the EVE_CALLBACK_URL without /auth/eve/callback suffix DB_HOST 127.0.0.1 This is the IP or domain from your SQL Server. DB_PORT 3306 This is the port used by your SQL Server to receive query. DB_DATABASE seat This is the name for your SeAT database. DB_USERNAME seat This is the user which is granted to the SeAT database from SeAT server. DB_PASSWORD secret This is the user password MAIL_DRIVER smtp This is the driver used to send mail. It will be covered in a dedicated article. MAIL_HOST smtp.mailtrap.io This is driver mail hostname. It will be covered in a dedicated article. MAIL_PORT 2525 This is the driver mail port. It will be covered in a dedicated article. MAIL_USERNAME null This is the driver mail username. It will be covered in a dedicated article. MAIL_PASSWORD null This is the driver mail password. It will be covered in a dedicated article. MAIL_ENCRYPTION null This is the driver mail encryption. It will be covered in a dedicated article. MAIL_FROM_ADDRESS noreply@localhost.local This is the mail address which the user will chown when he will receive mail from SeAT. MAIL_FROM_NAME SeAT Administrator This is the name which the user will chown when he will receive mail from SeAT. EVE_CLIENT_ID null This is the EVE Application Client ID you'll get when you created an application over https://developers.eveonline.com EVE_CLIENT_SECRET null This is the EVE Application Client Secret you'll get when you created an application over https://developers.eveonline.com EVE_CALLBACK_URL https://seat.local/auth/eve/callback This is the EVE Application Callback URL you filled when you created an application over https://developers.eveonline.com. You should have only to fix seat.local QUEUE_BALANCING_MODE false Determine the workers balancing mode used by the Jobs Manager. Value can be false, auto or simple. See official Laravel documentation for more details QUEUE_WORKERS 4 Determine the amount of worker which have to be spawn to process jobs over all queues. In auto and simple balancing, this value cannot be lower than 4 as it's correspond to the available queues."},{"location":"configuration/esi_configuration/","title":"ESI Configuration","text":""},{"location":"configuration/esi_configuration/#configuring-eve-online-esi-scopes","title":"Configuring Eve Online ESI-Scopes","text":""},{"location":"configuration/esi_configuration/#introduction","title":"Introduction","text":"

For normal operations within SeAT, authentication is provided by EVE Onlines' SSO service and API access with ESI and tokens supplied via SSO. Technical details behind the SSO implementation can be found here.

Authenticating users using SSO effectively means that users may authenticate to SeAT using their existing EVE Online credentials. SeAT does not have access to the credentials itself as that is handled entirely by CCP. Only once authentication is successful from an EVE Online perspective does a user get asked if they want to allow your SeAT installation to have access with the configured set of scopes. Once the user agrees to these scopes, the users browser is redirect back to SeAT and will be logged in.

If you have not configured this yet, the login page will present you with a warning about it:

"},{"location":"configuration/esi_configuration/#configuration-summary","title":"Configuration Summary","text":"

A bit of setup work is needed in order to have your SeAT setup ready for SSO integration and ESI usage. The gist of it is:

  • Step I: Register your application on the EVE Online Developers portal for both Authentication and API Access.
  • Step II: Configure your EVE_CLIENT_ID, EVE_CLIENT_SECRET and EVE_CALLBACK_URL in the .env configuration file
"},{"location":"configuration/esi_configuration/#register-your-application","title":"Register your application","text":"

Browse to the EVE Online Developers portal and create a new Application.

Give your application a meaningful Name and a Description. Users will see this name when they review the access Third Party applications have to their account so keep that in mind when registering your application.

Next, set the connection type to Authentication & API Access (1), select the ESI Scopes you want (probably all of them) (2) and specify the Callback URL (3)

To select ESI Scopes you can search for them in Available Scopes (2) and select the desired scope. The selected scope then will moved to (3).

Note on the Callback URL

The Callback URL where the user should be redirected to once authentication was successful. In other words, once they have completed authentication using their EVE Online credentials, they need to be redirected back to your SeAT instance. In the example above, we can see it is https://seat.local/auth/eve/callback. You should replace the seat.local part with your domain!

For example, assuming you are hosting SeAT at https://this.is.seat/, then the Callback URL will be https://this.is.seat/auth/eve/callback. If you have SeAT in a sub folder on your web server, remember to add the folder name before /auth/eve/callback.

With the new application created, you will now have the EVE_CLIENT_ID, EVE_CLIENT_SECRET that you need to configure in SeAT itself. Take note of these values.

"},{"location":"configuration/esi_configuration/#set-config-parameters-in-env-file","title":"Set config parameters in .env file","text":"

We are almost done. The next thing to do is to add the configuration parameters to our SeAT installs .env file. Browse to your SeAT installation directory and edit the .env file (note this is a hidden file and wont show up when you just type ls).

Look for the following section of the file and populate the values with those you got when you created an application on the developers site:

EVE_CLIENT_ID=null\nEVE_CLIENT_SECRET=null\nEVE_CALLBACK_URL=http://seat.test/auth/eve/callback\n
"},{"location":"configuration/esi_configuration/#notes-for-docker-users","title":"Notes for Docker Users","text":"

Your .env file is located in /opt/seat-docker. Rebuild your app after setting the ESI Details in it using:

Docker (SeAT 4.x)Docker (SeAT 5.x - using Traefik)Docker (SeAT 5.x - using proxy) 
docker-compose down\ndocker-compose up -d\n
docker compose down\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n
docker compose down\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n
"},{"location":"configuration/eve_administrative_contact/","title":"EVE Administrative Contact","text":""},{"location":"configuration/eve_administrative_contact/#eve-api-administrative-contact","title":"Eve API Administrative Contact","text":""},{"location":"configuration/eve_administrative_contact/#what","title":"What","text":"

Requests to the EVE API need to have an administrative contact email set before SeAT will queue jobs to process. CCP made the request in this Github issue. To address this, the email address is added to the User-Agent string that is used when making EVE API requests as can be seen eveseat/eveapi:Helpers/PhealSetup#L77.

"},{"location":"configuration/eve_administrative_contact/#why","title":"Why","text":"

The error Failed to queue due to default config is generated by eveseat/eveapi:Traits/JobManager#L47-L56 check. In order for this check to pass, you need to configure the administrative email address in the SeAT configuration.

"},{"location":"configuration/eve_administrative_contact/#how","title":"How","text":"

Adding the email address can be done in two ways. Wither via the command line or via the Web interface.

"},{"location":"configuration/eve_administrative_contact/#web-interface","title":"Web interface","text":"

The other method to change the admin email is via the web interface. You need to be logged in with a user that has the superuser role. Typically, if the email address is not set, you may notice the following warning on the home page:

To configure it, browse to Configuration -> SeAT Settings from the side menu, and set the email in the Administrator Email field.

"},{"location":"configuration/eve_administrative_contact/#command-line","title":"Command line","text":"

The command php artisan seat:admin:email will prompt you to add a valid email address for the administrative contact:

Example:

"},{"location":"configuration/sde_overload/","title":"SDE Overload","text":"

SeAT sources information about the SDE from a json file hosted here. It may happen that the SDE gets updated but the the json resource has not yet been updated. For this reason, its possible to specify the version to get based on what is available on www.fuzzwork.co.uk.

"},{"location":"configuration/sde_overload/#overriding-the-resources-json","title":"Overriding the resources json","text":"

Check the version of SDE dumps available on www.fuzzwork.co.uk. At the time of this writing, frostline-1.0-116241 was the latest. Once you have the version string ready, open the .env configuration file and add a key as follows:

SDE_VERSION=frostline-1.0-116241\n

When running the SDE updater, specify the --local parameter to source the version string from the configuration file:

php artisan eve:update:sde --local\n

Info

By default, SeAT automatically updates the SDE every month. You may want to login as an administrator and remove the schedule to update it monthly if you have overridden the default.

"},{"location":"configuration/email_setup/gmail/","title":"GMail","text":""},{"location":"configuration/email_setup/gmail/#email-setup-using-gmail","title":"Email Setup - Using GMail","text":""},{"location":"configuration/email_setup/gmail/#introduction","title":"Introduction","text":"

SeAT requires email to be setup to allow for things like notifications to be sent. This guide will attempt to describe how to go about setting up your email using GMail as an SMTP.

"},{"location":"configuration/email_setup/gmail/#the-config","title":"The config","text":"

As with anything Laravel, the config for your email setup will live in your installs .env file. To use GMail as an SMTP service, set the MAIL_DRIVER option in your .env configuration file to smtp. Next, specify the SMTP details:

// File: .env\n\nMAIL_DRIVER=smtp\nMAIL_HOST=smtp.gmail.com\nMAIL_PORT=587\nMAIL_USERNAME=username@gmail.com\nMAIL_PASSWORD=gmailpassword\nMAIL_ENCRYPTION=tls\nMAIL_FROM_ADDRESS=username@gmail.com\n

Done! To test, you can add some mail notification using the Integrations and Notification groups.

"},{"location":"configuration/email_setup/mailgun/","title":"Mailgun","text":""},{"location":"configuration/email_setup/mailgun/#email-setup-using-mailgun","title":"Email Setup - Using Mailgun","text":""},{"location":"configuration/email_setup/mailgun/#introduction","title":"Introduction","text":"

SeAT requires email to be setup to allow for things like notifications to be sent. This guide will attempt to describe how to go about setting up your email using the Mailgun service. Though Mailgun is a commercial service, you get to send 10k emails for free per month. It also provides epic stats for you to track emails with etc.

"},{"location":"configuration/email_setup/mailgun/#the-config","title":"The config","text":"

As with anything Laravel, the config for mailgun will live in your installs .env file. To use the Mailgun driver, first set the MAIL_DRIVER option in your .env configuration file to mailgun. Next, we will add two options to specify details about our mailgun account.

// File: .env\n\nMAILGUN_DOMAIN=whateveritis\nMAILGUN_SECRET=anotherthing\n

To find out the values you need to populate, login to your mailgun account and browse to the domains section. Pick the applicable domain name. The screen you will see should looks something similar to this:

The big title (sandbox1XXXXXXX in my case) is the domain name, and the field titled API Key is the MAILGUN_SECRET.

Done! To test, you can add some mail notification using the Integrations and Notification groups.

"},{"location":"developer_guides/core_package_breakdown/","title":"Core Package Breakdown","text":""},{"location":"developer_guides/core_package_breakdown/#developers-guides-core-package-breakdown","title":"Developers Guides - Core Package Breakdown","text":""},{"location":"developer_guides/core_package_breakdown/#understanding-the-core-seat-packages","title":"Understanding the core SeAT packages","text":"

This section aims to describe the functional differences between the various SeAT packages.

"},{"location":"developer_guides/core_package_breakdown/#eveseatapi","title":"eveseat/api","text":"

Namespace: Seat\\Api

Source Code: link

This repository contains all the SeAT Api Endpoints, as well as the routes and views for API key management.

"},{"location":"developer_guides/core_package_breakdown/#eveseateveapi","title":"eveseat/eveapi","text":"

Namespace: Seat\\Eveapi

Source Code: link

This repository is the heart of the API update logic. It is responsible for doing the actual update work, pulling the EVE API documents from ESI, parsing them and storing the resultant data in the database. Most of the data models live in this repository too.

"},{"location":"developer_guides/core_package_breakdown/#eveseatnotifications","title":"eveseat/notifications","text":"

Namespace: Seat\\Notifications

Source Code: link

This repository contains a set of scheduled jobs that perform notifications type tasks. A notification can be something as simple as an alert about a corporation member that has been inactive for a period of time.

"},{"location":"developer_guides/core_package_breakdown/#eveseatweb","title":"eveseat/web","text":"

Namespace: Seat\\Web

Source Code: link

This repository contains the web interface for SeAT. It contains by far the most complex service provider and will undoubtedly become the prime example/reference when developing packages for SeAT. This package is also the only one that has a permissions / ACL concept. Refer the to the permissions document for more information.

"},{"location":"developer_guides/core_package_breakdown/#eveseatseat","title":"eveseat/seat","text":"

Namespace: App

Source Code: link

This is the main SeAT repository. It does not really contain much logic. In fact, it should just be seen as the glue between all the core packages. This is the repository that is cloned when a new installation is done.

The most important part of this repository is the service providers that are bootstrapped with the application. The providers array has the default Laravel providers as well as the SeAT providers at the end. These providers tell the application where to find routes, views, configs etc. For more detailed information about providers, refer to the Laravel 5.5 documentation. When you write your package though, you should make use of package discovery as described in the Laravel 5.5 documenation. This will make the installation of your package super simple without the need to edit any files.

"},{"location":"developer_guides/core_package_breakdown/#eveseatservices","title":"eveseat/services","text":"

Namespace: Seat\\Services

Source Code: link

This repository contains 'services'. A service is defined as any form of helper and or repository that other packages can depend on. The eveseat/web package (amongst others) make heavy use of the repository classes in this package.

"},{"location":"developer_guides/developer_installation/","title":"Developer Installation","text":""},{"location":"developer_guides/developer_installation/#developer-installation","title":"Developer Installation","text":"

Since SeAT 4 and including SeAT 5, starting with Docker build 4.1.0, spawning a development environment has been made easier. You can use the same image as of production environment - either you're working on core packages or third party ones.

"},{"location":"developer_guides/developer_installation/#general","title":"General","text":"

First, start with standard installation to get a working environment.

The official docker-compose wrapper is shipped with a packages directory. It is mounted readonly, and you can store your development sources in it.

To make things easier, we recommend you keep vendor path convention to split your sources across every single package you want to play with.

Developing plugins and core packages doesn't differ at all, modules installed in the packages directory always take priority. In the case of core modules, this means the version from packages and not the version provided by the docker container will be used.

"},{"location":"developer_guides/developer_installation/#overrider","title":"Overrider","text":"

The image has been designed to look for a file called override.json inside packages directory. When it is found, it will be merged together with standard composer.json file from eveseat/seat package.

It's designed to override both autoload and providers. Here is a complete override.json structure:

{\n\"autoload\": {\n\"namespace_to_load\\\\\": \"packages/sources_path\"\n},\n\"providers\": [\n\"FQCN\\\\Provider\"\n]\n}\n

An override can have either autoload, providers or even both property. Do not forget to escape \\ in order to get a valid json file.

When your container will start, mapping from autoload property in your override.json file will be merged with autoload-dev property from official composer.json.

SeAT 4.x

  1. If you need access the console of any container, access it via docker exec seat-web sh where seat-web is the name of the target container.
  2. You can execute artisan commands from outside of docker with docker exec seat-web php artisan <command>

SeAT 5.x

  1. If you need access the console of any container, access it via docker exec front sh where front is the name of the target container.
  2. You can execute artisan commands from outside of docker with docker exec front php artisan <command>

Please note that there is currently no way to install dependencies with the package override.

"},{"location":"developer_guides/developer_installation/#teach-things-by-example","title":"Teach things by example","text":"

As an example, let's say I want to make a new feature in web core package, I'll spawn an eveseat directory at root packages directory, followed by a clone from eveseat/web git repository. Last but not least, I'll create an override.json file to inform SeAT there are developer things to load.

  1. Create vendor directory into packages directory mkdir packages/eveseat
  2. Cloning core web package into packages/eveseat/web directory git clone https://github.com/eveseat/web.git packages/eveseat/web
  3. Create an override.json to use custom web sources
cat > packages/override.json << EOL\n{\n  \"autoload\": {\n    \"Seat\\\\Web\\\\\": \"packages/eveseat/web/src/\"\n  }\n}\nEOL\n

Tips

If you're working with Windows, prefer to store your files in wsl layer rather than Windows directory. Both work, however, you'll get better performances!

"},{"location":"developer_guides/development_tips/","title":"Development Tips","text":""},{"location":"developer_guides/development_tips/#development-tips","title":"Development Tips","text":"

This page contains general tips and tricks that may be useful during package development.

"},{"location":"developer_guides/development_tips/#best-practices","title":"Best practices","text":"

No doubt, there are no limits to what code you can write, how you structure it and how you name things. However, the last thing you want is to have conflicts with the SeAT core, or someone elses package! The following list contains some tips to help you avoid those conflicts and to help people better discover your packages:

  • Prefix your github repository name with seat eg: seat-teamspeak.
  • Tag your github repository with seat.
  • Use a unique package namespace such as Author\\Seat\\Package\\ eg: Warlof\\Seat\\Teamspeak\\.
  • Prefix your database table names with something unique to your package. eg warlof_teamspeak_users. Although you shouldn't make your prefix too long, as there is a 64 character table length limit.
  • Do not modify core tables. This will break future updates for users of your package.
  • Prefix your settings with both an author and package eg: warlof.teamspeak.address.
  • Prefix redis records with both author and package eg: warlof.teamspeak.channels.
  • In your composer.json file, set the type to seat-plugin.
  • Avoid altering core tables, especially introducing relationship - this might break core migrations. Prefer to use observer if you need to maintain your data across core models.
  • If you need an API or something the SeAT core doesn't provide, consider contributing it. The SeAT core is not set in stone.
  • Scope your routes: For example all routes from the seat core start with seatcorelike this: seatcore::my.route.to.someting. You should follow a similar format: seat<plugin name>::<route>
"},{"location":"developer_guides/development_tips/#model-observers","title":"Model Observers","text":"

Depending on what your package does, it may be interesting for you to know when data is created / deleted. Given that SeAT makes use of Laravel, you have the ability to subscribe to events that occur on any model within SeAT.

For example, should a User model get deleted, the deleted event will get fired. Writing an observer class and subscribing to it with \\Seat\\Web\\Models\\User::observer(\\My\\Namespace\\UserObserver::class) will allow you to define a deleted() method inside of your observer class and perform extra logic with the User that got deleted.

Examples of where this may be interesting could be if you need to have cleanup code for tables that your package includes.

For more information, checkout the Laravel documentation on Eloquent Observers.

"},{"location":"developer_guides/job_queue_flow/","title":"Job Queue Flow","text":""},{"location":"developer_guides/job_queue_flow/#job-queue-flow","title":"Job Queue Flow","text":"

When a job is queued, it's instance is serialized and push into the Redis database. Horizon, our jobs orchestrator is taking care of every new jobs falling in redis and push it to an available worker from the targeted queue.

With SeAT 4, queues have been renamed and are scoped. This helps to identify load per \"topic\" and ensure better parallel processing of jobs.

As shown bellow, queues characters, corporations and public are dedicated to ESI jobs.

  • Characters queue is processing all jobs directly tied to a character entity (like info, assets, contracts, etc...)
  • Corporations queue is processing all jobs directly tied to a corporation entity (like killmails, jobs, wallets, etc...)
  • Public queue is processing all jobs related to universe (like stations, alliances, sovereignties, etc...)

There is a dedicated queue to handle notifications tasks (like notifying a killmail on Discord). So, you will always get your notifications as fast as possible.

The last two other queues (high and default) have a general purpose.

  • The high queue is dedicated to jobs which have a critical level (like those related to security)
  • The default queue is a bucket collecting all jobs without any other specified queue

The default (and recommended) jobs handling configuration is using auto balancing. This ensures every single queue always have a minimum of workers (1 is the default value).

Important

There are no ranking in queues, so, the high one is not most important than other in the way jobs are processing. Queue name doesn't influe on their ability to process load. So, please use high queue for really important/critical tasks only.

An editable draw.io xml to import can be found here: seat_jobs_flow.drawio

"},{"location":"developer_guides/notifications_implementation/","title":"Notifications Implementation","text":""},{"location":"developer_guides/notifications_implementation/#developers-guides-notifications-implementation","title":"Developers Guides - Notifications Implementation","text":"

Seat 5

This guide is already updated for seat 5. Older versions of this guide can be found on github.

"},{"location":"developer_guides/notifications_implementation/#introduction","title":"Introduction","text":"

SeAT is shipped with a built-in notification system which is able to send message across the world to almost any platform.

It is supporting e-mail, Slack and Discord out of the box.

However, thanks to Laravel, if you need to support another platform - you simply need to implement the related driver. See official Laravel Notification Channels website to get more about this.

Additionally, there is a system to mention certain users when a notification gets sent. Since we don't assume that many people need to implement this for a new platform, there is no written documentation. This is a good starting point to read the code: Config/notifications.mentions.php

"},{"location":"developer_guides/notifications_implementation/#configuration","title":"Configuration","text":"

All notifications must be declared inside notifications.alerts.php. You will want to create a file named like this in the Config directory of your plugin and then use mergeConfigFrom in your service provider to merge the seat core and plugin notification configuration. Every entry must follow this pattern:

'created_user' => [\n    'label' => 'notifications::alerts.created_user',\n    'handlers' => [\n        'mail' => \\Seat\\Notifications\\Notifications\\Seat\\Mail\\CreatedUser::class,\n        'slack' => \\Seat\\Notifications\\Notifications\\Seat\\Slack\\CreatedUser::class,\n    ],\n]\n
  • the entry key created_user must be unique overall system and will identify the very specific notification declaration. It will reference the notification definition composed of label and handlers keys.
  • the label will reference a translation token - this is the value which will appear on user interface into notification settings
  • the handlers key is containers a list of available formatters. There is a formatter per available platform - or so called - channel.
  • the optional visible key hides the notification from the list of available notifications, but you can still use the seat notification infrastructure normally. Realistically, you don't need this for anything.

You can also look at the seat core notifications.alerts.php file as an example.

"},{"location":"developer_guides/notifications_implementation/#formatters","title":"Formatters","text":"

Formatters are class which will define how message targeting a specific channel must be structured. In upper example, we have two formatters:

  • \\Seat\\Notifications\\Notifications\\Seat\\Mail\\CreatedUser which is handling mail channel format
  • \\Seat\\Notifications\\Notifications\\Seat\\Slack\\CreatedUser which is handling Slack channel format

Formatter must extend a different abstract class depending on what kind of platform it supports:

  • Discord: Seat\\Notifications\\Notifications\\AbstractDiscordNotification
  • Slack: Seat\\Notifications\\Notifications\\AbstractSlackDiscordNotification
  • Mail: Seat\\Notifications\\Notifications\\AbstractMailNotification

Every formatter is composed of the following method:

  • populateMessage(Message $message, mixed $notifiable) which will generate the structure message for the target platform. The type of Message differs slightly according to which platform you're on, e.g. on discord it is a Seat\\Notifications\\Services\\Discord\\Messages\\DiscordMessage, on slack it is a Illuminate\\Notifications\\Messages\\SlackMessage.
"},{"location":"developer_guides/notifications_implementation/#observers","title":"Observers","text":"

In SeAT, notifications are event based and sent by jobs queued in notifications queue. This prevents to lock system while sending the information.

To send your notification, you will listen for system events (ie: a character notification created in the database) in order to dispatch the selected notification.

"},{"location":"developer_guides/notifications_implementation/#characters","title":"Characters","text":"

All characters related notifications are handled by \\Seat\\Notifications\\Observers\\CharacterNotificationObserver

It is waiting for an Eve Online notification targeting a character to be registered and dispatch the related message to the requested platform - if asked for.

SeAT is shipped with numerous notifications - but due to the number of existing ones and the fact that there are regularly news notifications created by CCP attached to added features, it might append that a notification isn't handled.

You can track such cases using debug log level which will generate a log entry looking like this:

Unsupported notification type.\\ type: TheNotificationTypeAsPerESIDefinition (see: https://esi.evetech.net/ui/#/Character/get_characters_character_id_notifications)\\ sender_type: character\\ notification: the YAML structure of the notification

You'll find all standard notifications handler related to character into the following namespace: \\Seat\\Notifications\\Notifications\\Characters

"},{"location":"developer_guides/notifications_implementation/#corporations","title":"Corporations","text":"

Most of the corporations related notifications are handled by \\Seat\\Notifications\\Observers\\CharacterNotificationObserver

It is waiting for an Eve Online notification targeting a corporation to be registered and dispatch the related message to the requested platform - if asked for.

SeAT is shipped with numerous notifications - but due to the number of existing ones and the fact that there are regularly news notifications created by CCP attached to added features, it might append that a notification isn't handled.

You can track such cases using debug log level which will generated a log entry looking like this :

Unsupported notification type.\\ type: TheNotificationTypeAsPerESIDefinition (see: https://esi.evetech.net/ui/#/Character/get_characters_character_id_notifications)\\ sender_type: corporation\\ notification: the YAML structure of the notification

Alternatively, notifications related to corporation member state are handled by \\Seat\\Notifications\\Observers\\CorporationMemberTrackingObserver

You'll find all standard notifications handler related to corporation into the following namespace: \\Seat\\Notifications\\Notifications\\Corporations

"},{"location":"developer_guides/notifications_implementation/#killmails","title":"Killmails","text":"

All killmails related notifications are handled by \\Seat\\Notifications\\Observers\\KillmailNotificationObserver

It is waiting for a killmail being registered and dispatch the related message to the requested platform - if asked for.

"},{"location":"developer_guides/notifications_implementation/#squads","title":"Squads","text":"

All squads related notifications are handled by \\Seat\\Notifications\\Observers\\SquadApplicationObserver and \\Seat\\Notifications\\Observers\\SquadMemberObserver

It is waiting for squads members and applications to be registered and dispatch the related message to the requested platform - if asked for.

You'll find all standard notifications handler related to Squads into the following namespace: \\Seat\\Notifications\\Notifications\\Seat

"},{"location":"developer_guides/notifications_implementation/#users","title":"Users","text":"

All users related notifications are handled by \\Seat\\Notifications\\Observers\\UserObserver

It is waiting for a user to be registered and dispatch the related message to the requested platform - if asked for.

You'll find all standard notifications handler related to character into the following namespace: \\Seat\\Notifications\\Notifications\\Seat

"},{"location":"developer_guides/notifications_implementation/#porting-plugins-from-seat-4-to-5","title":"Porting Plugins from Seat 4 to 5","text":"

All notifications continue to work without any changes, even though there have been major refactors. However, to profit of the new mentions system behind discord pings, you need to change a few things to update to the new notification structure:

  • Start extending from the platform specific classes instead of Seat\\Notifications\\Notifications\\AbstractNotification.
  • Discord: extend Seat\\Notifications\\Notifications\\AbstractDiscordNotification
  • Slack: extend Seat\\Notifications\\Notifications\\AbstractSlackDiscordNotification
  • Mail: extend Seat\\Notifications\\Notifications\\AbstractMailNotification
  • Remove the via method. It moved to the abstract notification class.
  • Refactor your public toX() method to a protected populateMessage(Messagetype $message, $notifiable). Instead of creating a new message, use the parameter $message. The type Message must be adjusted depending on your platform:
  • discord: Seat\\Notifications\\Services\\Discord\\Messages\\DiscordMessage
  • slack: Illuminate\\Notifications\\Messages\\SlackMessage
  • mail: Illuminate\\Notifications\\Messages\\MailMessage
  • Consider using the Seat\\Notifications\\Traits\\NotificationDispatchTool trait to dispatch notification. It helps to deduplicate the most common logic.

The old plugin structure will stop working in seat 6.

"},{"location":"developer_guides/package_development/","title":"Package Development","text":""},{"location":"developer_guides/package_development/#developers-guides-package-development","title":"Developers Guides - Package Development","text":""},{"location":"developer_guides/package_development/#introduction","title":"Introduction","text":"

So, you want to write a SeAT package? Hopefully this guide helps you along the way! This guide was written while writing the API package for SeAT here. I figured it would be best to try and capture the process to help in case I miss any important details.

Be sure to also have a look at the Development Tips page!

"},{"location":"developer_guides/package_development/#background-notes","title":"Background notes","text":"

I think its important to keep in mind a few things about how SeAT is put together. The most important being a brief description of what each core package offers, and how you can integrate with them. For a breakdown on what the core packages provide, please refer the to [breakdown].

SeAT 4 is written on Laravel 6, while SeAT 5 uses Laravel 10. A very good thing to do would be to actually read the documentation top->bottom and get an idea of what is possible with the framework. SeAT core packages make heavy use of many of the features, based directly of what has been interpreted by this very documentation.

If you really want to start contributing packages, but just cant get your head around this whole Laravel thing, then I can suggest you have a look at this excellent free course material covering the basics of what you will encounter in the SeAT codebase. https://laracasts.com/series/laravel-6-from-scratch

Other plugins and the SeAT core are also a good learning resource.

"},{"location":"developer_guides/package_development/#getting-started","title":"Getting started","text":"

The very first thing to do is prepare the empty git repository on say Github, as well as the composer package itself. Clone a clean repository, and run composer init, answering any questions. Once that is done, edit the resultant composer.json and prepare the autoload block. SeAT core follows the PSR-4 autoloading standard. I will suggest you do the same. For some more detailed composer info, refer to the docs here. For the API package, I am going to autoload Seat\\Api from the src directory using PSR-4.

"},{"location":"developer_guides/package_development/#service-provider","title":"Service provider","text":"

As mentioned in the package breakdowns, the eveseat/seat repository bootstraps packages via service providers or package discovery. This is actually a Laravel convention that SeAT just follows. To get our package ready, we need to create a service provider. For the API package, I create an ApiServiceProvider class in src/ directory which extends Seat\\Services\\AbstractSeatPlugin. Our packages file structure now looks as follows:

\u251c\u2500\u2500 composer.json\n\u2514\u2500\u2500 src\n    \u2514\u2500\u2500 ApiServiceProvider.php\n

Hint

The AbstractSeatPlugin class is extending Laravel ServiceProvider class and ship you with useful methods that help to register your plugin in the stack (including version discovery, permissions registration, etc...). You must use it rather than the standard one, especially if you want permissions and get your packages in Settings > SeAT Settings > SeAT Module Versions pane.

"},{"location":"developer_guides/package_development/#package-structure","title":"Package structure","text":"

From here you pretty much free to do what you want. How you structure the package will obviously depend on what exactly your package provides. In principle, I prefer to follow the same package structure as Laravel does for web / console features. Since we are going to be providing web features with the API, we will quickly create a few folders in preparation for this. I know beforehand that we are going to need a model to store API tokens; middleware to authenticate API requests; routes and controllers for the actual api logic (preferably making use of the eveapi/services repository classes for data access) as well as a few web views for administrators to generate API tokens for applications. With that in mind, the initial structure looks as follows:

\u251c\u2500\u2500 composer.json\n\u2514\u2500\u2500 src\n    \u251c\u2500\u2500 ApiServiceProvider.php\n    \u251c\u2500\u2500 Config\n    \u251c\u2500\u2500 Http\n    \u2502\u00a0\u00a0 \u251c\u2500\u2500 Controllers\n    \u2502\u00a0\u00a0 \u2514\u2500\u2500 Middleware\n    \u251c\u2500\u2500 Models\n    \u251c\u2500\u2500 database\n    \u2502\u00a0\u00a0 \u2514\u2500\u2500 migrations\n    \u2514\u2500\u2500 resources\n        \u2514\u2500\u2500 views\n

This will obviously change as we progress building the package.

"},{"location":"developer_guides/package_development/#routes-and-controllers","title":"Routes and controllers","text":"

To start testing the API, we need to add a route and controller to process some requests and responses. My routes.php file will have a global Route::group() to encapsulate the routes in the Seat\\Api namespace as well as prefix them with api/.

// File: routes.php\nRoute::group([ 'namespace' => 'Seat\\Api\\Http\\Controllers',\n    'prefix' => 'api'\n], function () {\n    // Logic here\n});\n

See the final product here for a more complete example.

Next, I add some logic with a route to /, update the base frameworks composer.json to autoload the Seat\\Api namespace from the directory where my package lives, run composer dump-autoload and add the service provider to the eveseat/seat repositories app.php providers array. Lastly, I add a method to the service provider to load the routes and call it form the boot() method in the generated stub.

See the complete service provider here

/**\n* Include the routes\n*/\npublic function add_routes()\n{\n    if (!$this->app->routesAreCached()) {\n        include __DIR__ . '/Http/routes.php';\n    }\n}\n

As a final test, I check that my route is accessible from a booted SeAT app. :)

"},{"location":"developer_guides/package_development/#routes","title":"Routes","text":""},{"location":"developer_guides/package_development/#access-control","title":"Access Control","text":"

Obviously, some routes are not for everyone's eyes. SeAT comes with middleware that can be used to filter out requests that may not be authorized for your route. As can be seen in the example below (from here), we are filtering out requests to api-admin for only superusers.

Route::group([\n        'namespace'  => 'Admin',\n        'middleware' => ['auth', 'can:global.superuser'], // The ACL specification.\n        'prefix'     => 'api-admin'\n    ], function () {\n        Route::get('/', [\n            'as'   => 'seatcore::api-admin.list',\n            'uses' => 'ApiAdminController@listTokens']);\n    });\n

I suggest you have a look at the eveseat/web packages routes definitions for more examples on how the middleware is used. https://github.com/eveseat/web/tree/master/src/Http/Routes

It is recommended that you scope the route name defined in 'as' => 'seatcore::api-admin.list'. For example all routes from the seat core start with seatcore like this: seatcore::my.route.to.someting. You should follow a similar format: seat<plugin name>::<route>

"},{"location":"developer_guides/package_development/#middleware","title":"Middleware","text":"

To auth our API requests, we are going to go with token based authentication for now. We want users to present us with a X-Token header (from a valid allowed src IP address) before they may proceed with their request. To do this, we will filter requests using middleware. Thankfully, again, Laravel comes with a command to stub us some empty middleware. Run php artisan make:middleware ApiToken and copy it to your projects Middleware folder. Next we should register the middleware in our service provider. I do this by adding a method and calling it in boot().

See the complete middleware here

/**\n * Include the middleware needed\n *\n * @param $router\n */\npublic function add_middleware($router)\n{\n    // Authenticate checks that the token is valid\n    // from an allowed IP address\n    $router->middleware('api.auth', ApiToken::class);\n}\n
"},{"location":"developer_guides/package_development/#views","title":"Views","text":"

Although almost all of our interfacing with this package will be via the json api endpoints, we need to add a few routes that will give an administrator the ability to generate API tokens as well as view logs etc. This will be for an administrator, so we will re-use the ACL features provided by the eveseat/web package to ensure that only admins an access our api-admin routes. Views live in resources/views and are bootstrapped to the api namespace in the service provider. See the service provider here for an example.

Note how we are re-using views that exist in the web namespace. All we have to do is extend one of the grids like here and start without our blade template.

"},{"location":"developer_guides/package_development/#sidebar-menu","title":"Sidebar menu","text":"

Integrating with the sidebar is also really easy. All you have to do is create a config file, bootstrap it in the service provider and viola. The config file itself has a set structure for the web package to interpret and can be seen here.

return [\n    'api' => [\n        'permission'    => 'global.superuser',\n        'name'          => 'Api Tokens',\n        'icon'          => 'fas fa-exchange',\n        'route_segment' => 'api-admin',\n        'entries'       => [\n            [   // Manage API Tokens\n                'name'  => 'Manage',\n                'icon'  => 'fas fa-key',\n                'route' => 'api-admin.list'\n            ]\n        ]\n    ]\n];\n

The format is generally an array, whereby the first key is the name of your package (api in this case). Thereafter you can specify the main entry, and any sub entries you want to add. The route key should refer to the named route. The sidebar loader will resolve the route itself for you. If you have any permissions requirements for your package, the permission key can be used together with a required SeAT permission to render the view.

"},{"location":"developer_guides/package_development/#character-submenus","title":"Character submenus","text":"

Integrating with the character sub menus is also really easy. Just like the sidebar, all you have to do is create a config file, bootstrap it in the service provider and viola. The namespace should be named package.character.menu in your service provider. A sample config file can be seen below:

// file: package.character.menu.php\nreturn [\n    [\n        'name'           => 'Research',\n        'permission'     => 'character.research',\n        'highlight_view' => 'research',\n        'route'          => 'character.view.research'\n    ]\n];\n
"},{"location":"developer_guides/package_development/#corporation-submenus","title":"Corporation submenus","text":"

Integrating with the corporation sub menus is also really easy. Just like the sidebar and character menus, all you have to do is create a config file, bootstrap it in the service provider and viola. The namespace should be named package.corporation.menu in your service provider. A sample config file can be seen below:

// file: package.corporation.menu.php\nreturn [\n    [\n        'name'           => 'Research',\n        'permission'     => 'corporation.research',\n        'highlight_view' => 'research',\n        'route'          => 'corporation.view.research'\n    ]\n];\n
"},{"location":"developer_guides/package_development/#bootstrapping-menu-items","title":"Bootstrapping menu items","text":"

In the above items, we refer to the files needing to be bootstrapped via the service provider. All this really means is that we have to tell the Laravel application where to find configuration information for a namespace. So, if we wanted to add a sidebar item, we would add the following line to the register() method of the service provider:

// Include this packages menu items\n$this->mergeConfigFrom(__DIR__ . '/Config/package.sidebar.php', 'package.sidebar');\n

The first argument is the file with the sidebar definitions, the second is the namespace.

"},{"location":"developer_guides/package_development/#permissions","title":"Permissions","text":"

You are able to register and use your own permissions for use within SeAT. This is relatively simple and done by creating a config file in the location Config/Permissions/package.permissions.php. It should return an array of the following format:

[\n    'sheet' => [\n        'label'       => 'Grant access to Character Sheet',\n        'description' => 'The Character Sheet contains basic information....',\n        'division'    => 'financial',\n    ],\n    'intel' => [\n        'label'       => 'web::permissions.character_intel_label',\n        'description' => 'web::permissions.character_intel_description',\n        'division'    => 'military',\n    ],\n    'planetary' => [\n        'label'       => 'web::permissions.character_planetary_label',\n        'description' => 'web::permissions.character_planetary_description',\n        'division'    => 'industrial',\n    ],\n];\n
property mandatory purpose label yes The displayed name of your permission. It must be a translation token. description The displayed permission description. It should help user to determine what the permission is doing. It must be a translation token. division It will show a \"category\" icon to help user figures what will be impacted by the permission. Value can be one of military, assets, financial, industrial. gate If you need to manage your permission with a custom policy, you can provide a policy FQCN.

The definition key (sheet, intel, planetary in the upper sample) will be used as permission unique identifier by the system. This is the one stored in the database, together with scope.

Info

By default, if no gate are provided, those shipped in core will be used according to this pattern :

  • character scope: CharacterPolicy, this will require an instance of CharacterInfo to be used in your checks
  • corporation scope: CorporationPolicy, this will require an instance of CorporationInfo to be used in your checks
  • anything else: GlobalPolicy

You'll find policy sample at this location.

In SeAT 4, a permission is made of a scope and an ability. The ability is defined by the permissions configuration file and the scope is defined on registration.

This config file is then loaded from your app service provider as below:

 $this->registerPermissions(__DIR__ . '/Config/Permissions/package.permissions.php', 'package');\n
"},{"location":"developer_guides/package_development/#database","title":"Database","text":"

For our API package, we have a database requirement. We need to store api tokens and the ip address that is allowed to use them. We are also going to store an access log (based on the config setting). We create migrations and models just like you would for a base Laravel 6 application. The only thing to remember is that your migrations for your package must be published (and specified in your service provider).

Registering these migrations looks like the following:

$this->loadMigrationsFrom(__DIR__ . '/database/migrations/');\n
"},{"location":"developer_guides/package_development/#releasing-the-plugin","title":"Releasing the plugin","text":"

The usual setup is to host the code on github and distribute the code via packagist. When you submit your plugin on packagist, it will be installable like the other plugins by adding <vendor>/<package> to the appropriate section of your .env file.

"},{"location":"developer_guides/seat_api/","title":"SeAT API","text":""},{"location":"developer_guides/seat_api/#introduction","title":"Introduction","text":"

SeAT has a REST API. Endpoints are protected by an access token that is limited by IP address. For every IP address that wants to make API requests to SeAT, a unique token is required. API Tokens have no concept of ACL's. The API should primarily be used for integrations with other systems.

"},{"location":"developer_guides/seat_api/#definitions","title":"Definitions","text":"

Currently, all API endpoints live at <seat url>/api/<version> where <seat url> is the full url to your SeAT instance and <version> is the API version you wish to interact with.

Since SeAT 3.0, API documentation is generated from source code annotations and presented via a Swagger UI. As a result, endpoint documentation is now directly available on your instance at the following address <seat url>/api/documentation. A link to the documentation is also provided on the API key management page available to users with the Superuser role.

Swagger JSON

If you get an error when viewing the API documentation that complains about a file called api-docs.json, make sure that you ran the php artisan l5-swagger:generate command as part of the installation and upgrade routines.

"},{"location":"developer_guides/seat_api/#authentication","title":"Authentication","text":"

Authentication to the SeAT API is done via a X-Token header. A token may be obtained by browsing to the API settings page in the SeAT WebUI and generating one. A sample request using curl with an authentication token can be seen below:

$ curl -X GET -H \"X-Token:123456\" -H \"Accept: application/json\" http://localhost:8000/api/v1/key\n*   Trying ::1...\n* Connected to localhost (::1) port 8000 (#0)\n> GET /api/v1/key HTTP/1.1\n> Host: localhost:8000\n> User-Agent: curl/7.43.0\n> Accept: application/json\n> X-Token:123456\n>\n< HTTP/1.1 200 OK\n< Host: localhost:8000\n< Connection: close\n< Cache-Control: no-cache\n< Date: Sat, 28 Nov 2015 22:27:12 GMT\n< Content-Type: application/json\n
"},{"location":"developer_guides/seat_api/#content-type","title":"Content-Type","text":"

Make sure you specify the Accepted content-type header as application/json. When using cURL, you can specify it with -H

Example:

$ curl -X POST https://seat.testsite.local/api/v1/key -H \"Accept: application/json\" -H \"X-Token: L3SxgdX4XUw6pVWVSCftgsh16eAbBF3D\" -d \"key_id=123&v_code=123\"\n{\"v_code\":[\"The v code must be 64 characters.\"]}\n

If you don't do this, the API will respond with a redirect and not give you the expected content.

"},{"location":"developer_guides/seat_api/#errors","title":"Errors","text":"

All SeAT API responses will include the appropriate HTTP response codes. You should check this for error handling purposes. Some sample response codes could be:

Code Status Description 200 OK The request was successful. 404 Not Found The requested endpoint could not be found. 422 Unprocessable Entity Typically, input validation has failed. The response json should contain the errors. 500 Internal Server Error Something bad has happened. Check the server and Laravel log files for more details."},{"location":"developer_guides/updating_plugins/","title":"Updating Plugins","text":""},{"location":"developer_guides/updating_plugins/#updating-plugins","title":"Updating Plugins","text":"

This page aims to help with porting a SeAT plugin to a newer version of seat.

"},{"location":"developer_guides/updating_plugins/#from-seat-4","title":"From SeAT 4","text":"

SeAT 5 mainly upgrades the php and laravel version as well as all dependencies to their newest version. However, there are a few other breaking changes that can't be ignored.

  • PHP 8.2: SeAT now runs on php 8.2, enabling new features like enums and better type hinting, but also breaking a few things.
  • Route Prefixing: All routes from the seat core start with seatcore::. For example, notifications.integrations.list turns into seatcore::notifications.integrations.list. If your plugin uses routes pointing to the seat core, you will have to update them.
  • Notifications: All notifications from SeAT 4 continue to work, but by updating them you can unlock more features like discord pings. See the notifications guide for more details.
  • The Seat\\Eveapi\\Jobs\\Middleware\\WithoutOverlapping job middleware backport is now provided by laravel and got removed from the SeAT core. Use Illuminate\\Queue\\Middleware\\WithoutOverlapping instead. Just swapping the import should be enough, as they are compatible.
  • Some, but not all ways of exporting data from DataTables are broken. Just check whether they work and fix if required.
  • There are a few minor breaking changes between Laravel 6 and 10:
  • MyJob::dispatchNow() got replaced with MyJob::dispatchSync()
  • For a full list, head over to the laravel documentation.
"},{"location":"developer_guides/updating_plugins/#from-seat-3","title":"From SeAT 3","text":"

If you're upgrading a SeAT 3.x plugin, the cheat sheet bellow will probably helps you.

SeAT 3.x SeAT 4.x Purpose auth()->user() auth()->user() Retrieve the currently authenticated user. auth()->user()->group->main_character auth()->user()->main_character Retrieve the main character from the currently authenticated user. auth()->user()->group->main_character->name auth()->user()->name Retrieve the main character name from the currently authenticated user. auth()->user()->group->characters auth()->user()->characters Retrieve all characters from the currently authenticated user. auth()->user()->refresh_token CharacterInfo()->refresh_token Retrieve the refresh token attached to a character. auth()->user()->group->refresh_tokens auth()->user()->refresh_tokens Retrieve all refresh tokens attached to authenticated user.

Also, if you need it, a table called mig_groups is available in database containing a list of all converted group into standalone user. This table will stay here until next SeAT major update.

Field Purpose group_id The unique ID from SeAT 3 user group old_user_id The unique ID from SeAT 3 user (match to Character ID) new_user_id The unique ID from SeAT 4 user main_character_id The SeAT 3 registered main character ID - or random from the User Group if none were set"},{"location":"installation/docker_installation/","title":"Docker Installation (5.x)","text":""},{"location":"installation/docker_installation/#docker","title":"Docker","text":"

Docker is ideally the installation route you want to go. Docker enables us to run SeAT on any platform capable of running docker itself (which includes Windows!). Additionally, upgrades and service maintenance are really low effort as you don't have to care about any dependencies. All of it is maintained within a docker stack, DockerHub and the GitHub Container Registry.

Windows owner recommendation

If you plan on running Docker on Windows, for the best performance it is suggested that you run Docker using the Windows Subsystem for Linux 2 (WSL2) backend, available starting in Windows 10/Windows Server 20H1 (build 2004) releases.

Windows owner special installation path

If you are using Docker on Windows, you will need to use the Manual Deployment option below.

Tip

Before starting the installation process, be sure you read this complete document first. It will help you understand all the steps from an installation process.

If you feel like docker might not be your cup of tea, checkout some of the other getting started guides that are available.

Eve Application and ESI

SeAT uses CCP's ESI service in order to retrieve EVE Online-related information. Before you can make any authenticated calls to ESI, you have to register a third-party EVE application on the developers portal. This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

"},{"location":"installation/docker_installation/#internal-container-setup-overview","title":"Internal Container Setup Overview","text":"

The setup for SeAT's docker installation orchestrated using docker-compose. With docker-compose, we can use YAML files to define the entire stack complete with all the dependencies required to run SeAT. A pre-built and recommended compose file (which is also used by the bootstrapping script) is hosted in the seat-docker repository here.

The official SeAT repository for Docker is shipped with a total of 4 YAML files, allowing you both flexibility and understandability of the overall stack. A high-level overview of its contents is:

  • A main docker-compose.yml file in which are listed SeAT services (front to serve web ui, worker to process jobs, scheduler to manage repetitive tasks and cache to store jobs queue)
  • A database docker-compose.mariadb.yml file in which is listed a mariadb service - this way, you can replace mariadb by another supported database engine
  • A Traefik docker-compose.traefik.yml file in which is listed a traefik service - this way you can simply and safely server your SeAT frontend to the rest of the world
  • An alternative to Traefik docker-compose.proxy.yml file in which is adapted front SeAT container to be server behind a reverse proxy of your choice
  • A volume called mariadb-data and seat-storage is defined. These are the most important volumes as they contain all SeAT data. You should configure a backup solution for them!
  • The environment is configured using a top-level .env file.
  • Only one port is exposed by default. This is tcp/8080. It can be connected to in order to access the SeAT web interface.
  • When using the stack with Traefik (which is the easier and recommended approach), ports tcp/80 and tcp/443 are exposed and tcp/8080 remain unbound.
  • All containers are configured to restart on failure, so if your server reboots or a container dies for whatever reason it should automatically start up again.

The table bellow is listed overall consumed Docker image, including SeAT custom one - together with their source repository.

Image Name Image Repository mariadb:10.11 https://hub.docker.com/_/mariadb/ redis:5-alpine https://hub.docker.com/_/redis/ traefik:2.10 https://hub.docker.com/_/traefik ghcr.io/eveseat/seat:5 https://github.com/eveseat/seat-docker/pkgs/container/seat"},{"location":"installation/docker_installation/#seat-docker-installation","title":"SeAT Docker Installation","text":"

Depending on whether you already have docker and docker compose already installed, you may choose how to start the installation. If you already have the required tooling installed and running their latest versions, all you need to do is download the latest SeAT Docker template archive to get started.

"},{"location":"installation/docker_installation/#automated-setup-script","title":"Automated Setup Script","text":"

If you do not have the required software installed yet, consider running the bootstrap script that will check for docker and docker compose, install it and start the SeAT stack up for you. The script can be run with:

bash <(curl -fsSL https://raw.githubusercontent.com/eveseat/seat-docker/master/bootstrap.sh)\n

Once the script is finished, you can skip to the monitoring the stack section of this guide.

If you don't want to run this script, follow along in the next section of this guide.

"},{"location":"installation/docker_installation/#manual-deployment","title":"Manual Deployment","text":""},{"location":"installation/docker_installation/#docker-download","title":"Docker Download","text":"

If you do not have docker, install it now.

LinuxWindows

Under Linux, you can achieve this action by using the following command as root:

sh <(curl -fsSL get.docker.com)\n

Under Windows, you can achieve this action by downloading and installing Docker Desktop.

"},{"location":"installation/docker_installation/#docker-compose-download","title":"Docker-compose Download","text":"

If you do not have docker compose, install it now with the following command as root (Docker Compose is included with Docker Desktop on Windows):

# Downloads and install docker compose from Docker repository\nsudo apt-get update\nsudo apt-get install docker-compose-plugin\n
"},{"location":"installation/docker_installation/#docker-compose-working-directory","title":"Docker compose working directory","text":"

With docker and docker compose ready, create yourself a directory in /opt with mkdir -p /opt/seat-docker and cd to it. Remember this directory as you will need to come back to it often.

On Windows, create the C:\\seat-docker directory with mkdir C:\\seat-docker and cd to it.

"},{"location":"installation/docker_installation/#seat-docker-composeyml-and-env-file","title":"SeAT docker-compose.yml and .env File","text":"

Then, download the SeAT Docker template archive with:

LinuxWindows 
curl -fsSL https://github.com/eveseat/seat-docker/archive/refs/heads/master.zip -o seat-docker.zip\n
Invoke-WebRequest -Uri https://github.com/eveseat/seat-docker/archive/refs/heads/master.zip -OutFile seat-docker.zip\n

Next, decompress the template archive:

LinuxWindows 
unzip seat-docker.zip -d /opt/seat-docker -j\n
Expand-Archive -Path c:\\seat-docker\\seat-docker.zip -DestinationPath c:\\seat-docker\n

Next, we will generate a unique application key - this is used internally for encryption:

LinuxWindows 
sed -i -- 's/APP_KEY=insecure/APP_KEY='$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c32 ; echo '')'/g' .env\n
$appkey = (-join ((65..90) + (97..122) | Get-Random -Count 32 | % {[char]$_})); (Get-Content .env -Raw) -replace \"APP_KEY=insecure\", \"APP_KEY=$appkey\" | Set-Content .env\n
"},{"location":"installation/docker_installation/#seat-docker-configuration","title":"SeAT docker configuration","text":"

Open up the .env file in a text editor and fill in a few of the configuration items needed.

  • PROXY_BACKEND_HTTP_PORT adapt to any integer of your convenience between 1 and 65535 in case you plan to serve SeAT behind a reverse proxy.
  • TRAEFIK_ACME_EMAIL adapt with your own e-mail address in case you plan to serve SeAT behind Traefik.
  • SEAT_DOMAIN should be set to the domain your installation lives on and on which SeAT UI will be served.
  • DB_PASSWORD must be adapt with a strong password of your own - it will be used as SeAT credential for its database.

Warning

The DB_PASSWORD value have to and must be changed only once - before any start of the overall stack. As soon as the database container is created, SeAT user account is initialized with the DB_PASSWORD value. Changing it after the initial startup will prevent the stack to boot.

Also, at the initial startup, the root password from the database container will be shown in logs. You should consider taking a note of it - otherwise you will no longer have a way to recovery of a critical outage (ie: misconfiguration, etc...)

Finally, in case you plan to serve SeAT using Traefik, create an ACME configuration file with:

mkdir acme\ntouch acme/acme.json\nchmod 600 acme/acme.json\n

Info

SeAT docker template is shipped with Traefik to hide your container behind a proxy and securing traffic up to it. In case you want to manage traffic proxying and certification on your own, you must use docker-compose.proxy.yml file on startup.

Warning

The location of the docker-compose.yml and .env files are important. You need to cd back to the directory where these are stored in order to be able to execute commands for this stack at a later stage.

Also, be sure you provide a valid e-mail address as it will be used to register your account against Let's Encrypt in case you plan to serve SeAT with Traefik. For those unfamiliar with this, it's CA that provides valid certificates for free.

"},{"location":"installation/docker_installation/#esi-configuration","title":"ESI Configuration","text":"

As mentioned at the start of the guide, it is necessary for you to configure ESI. For instructions on how to do this, please refer to the ESI Setup Guide.

With the configuration files ready, start up the stack with:

Using TraefikUsing proxy 
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up\n
"},{"location":"installation/docker_installation/#monitoring-the-stack","title":"Monitoring the Stack","text":"

Knowing what is going on inside your containers is crucial to understanding how everything is running as well as useful when debugging any problems that may occur. While the containers are starting up or have been running for a while, you can always cd to the directory where your docker-compose.yml file lives and run the logs command to see the output of all the containers in the stack. For example:

cd /opt/seat-docker\ndocker compose logs --tail 10 -f\n

These commands will cd to the directory containing the stacks docker-compose.yml file and run the logs command, showing the last 10 log entries and then printing new ones as they arrive. If you leave away the --tail 10part, you can view all logs since the container startup.

"},{"location":"installation/docker_installation/#configuration-changes","title":"Configuration Changes","text":"

All the relevant configuration lives inside the .env file, next to your docker-compose.yml file. Modify their values by opening it in a text editor, making the appropriate changes, and saving it again. Once that is done, restart the container environment:

Using TraefikUsing proxy 
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n

Success

You made it! Use a browser and browse to the domain / subdomain of your server to access SeAT!

"},{"location":"installation/manual_installation/","title":"Manual Installation (5.x)","text":""},{"location":"installation/manual_installation/#manual-installation","title":"Manual Installation","text":"

This guide attempts to explain how to manually install SeAT onto an Ubuntu Server. A small amount of Linux experience is preferred when it comes to this guide, although it is not entirely mandatory.

Info

This guide has been written targetting Ubuntu. However, you can use it to deploy SeAT on any linux distribution. Just be sure you adapt commands to targetted distribution (mostly those related to the package manager).

Hint

Before starting to do anything, be sure you read the complete workflow once. It will help you to understand all steps from the installation process.

Eve Application and ESI

SeAT consumes CCP's ESI service in order to retrieve EVE Online related information. Before you can make any authenticated calls to ESI, you have to register a third party EVE application on the developers portal. This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

"},{"location":"installation/manual_installation/#getting-started","title":"Getting started","text":"

We are going to assume you have root access to a fresh Ubuntu Server. Typically access is gained via SSH. All of the below commands are to be entered in the SSH terminal session for the installation & configuration of SeAT. If the server you want to install SeAT on is being used for other things too (such as hosting MySQL databases and or websites), then please keep that in mind while following this guide.

Packages are installed using the aptitude package manager as the root user.

"},{"location":"installation/manual_installation/#os-installation","title":"OS Installation","text":""},{"location":"installation/manual_installation/#operating-system","title":"Operating System","text":"

Before we get to installing SeAT, lets ensure that your operating system is up to date. We can do that with basics :

  • apt-get update to refresh the repositories cache.
  • apt-get full-upgrade to update any installed packages.
  • reboot in order to ensure any updated software is the current running version.
  • apt-get autoremove (after the reboot) to cleanup any unneeded packages.
"},{"location":"installation/manual_installation/#database","title":"Database","text":"

SeAT relies heavily on a database to function. Everything it learns is stored here, along with things such as user accounts for your users. It comes without saying that database security is a very important aspect too. So, ensure that you choose very strong passwords for your installation where required.

SeAT officially supports just MariaDB. Using MySQL or PostreSQL might appear to work on the surface, however it is likely that you will run into issues due to differences between the databases later down the line, and almost no testing with them is done during development.

We need to ensure that we have the latest MariaDB installed. To help with this, MariaDB provides an official repository to get the latest versions.

To download and install the repo, you need curl. Install it with:

apt-get install curl\n

Let's add this repository with:

curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | bash\n

With the repository now setup, lets install the database server:

Warning

During the installation, you may be asked to set a password for the root MariaDB user account. Make sure you set a long, strong password and remember it. It will be needed for the next step.

apt-get install mariadb-server\n

Before we can configure the database, we have to start it:

systemctl enable mariadb.service\n

Next, we are going to secure the database server by removing anonymous access and setting a root password (if you have not been prompted for it yet).

Note

The database root password should not be confused with the operating systems root passwords. They are both completely different. They should also not have the same password.

To secure the database, run:

mariadb-secure-installation\n

This will ask you a series of questions where you should generally just answer yes to. If you already set a root password in the previous step then you dont have to set it again, otherwise, make sure you choose a long, strong password for the root account. An example run is shown below:

[...]\nEnter current password for root (enter for none):  IF ONE WAS SET, IGNORE THIS\nOK, successfully used password, moving on...\n\n[...]\nSet root password? [Y/n] y\nNew password:             SET A STRONG PASSWORD HERE\nRe-enter new password:    SET A STRONG PASSWORD HERE\nPassword updated successfully!\nReloading privilege tables..\n ... Success!\n\n[...]\nRemove anonymous users? [Y/n] y\n ... Success!\n\n[...]\nDisallow root login remotely? [Y/n] y\n ... Success!\n\n[...]\nRemove test database and access to it? [Y/n] y\n\n[...]\nReload privilege tables now? [Y/n] y\n ... Success!\n\n[...]\n

That concludes the installation of the database server and securing it.

Next, we need to create an actual user and database for SeAT to use on the newly installed server. To do this we use the mariadb command line client and enter a few commands as the root user to create the database and the user that will be accessing the server. Let get to it.

Fire up the mariadb client as root by running:

mariadb -uroot -p\n

This will prompt you for a password. Use the password you configured for the root account when we ran mysql_secure_installation. This will most probably be the last time you need to use this password :)

If the password was correct, you should see a prompt similar to the one below:

root@ubuntu:~# mysql -uroot -p\nEnter password:\nWelcome to the MariaDB monitor.  Commands end with ; or \\g.\nYour MariaDB connection id is 16\nCopyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nMariaDB [(none)]>\n

Create a new database for SeAT to use with:

create database seat;\n

The output should be similar to the below:

MariaDB [(none)]> create database seat;\nQuery OK, 1 row affected (0.00 sec)\n

Next, we need to create the user that SeAT itself will use to connect and use the new seat database:

GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';\n

Of course, you need to replace s_p3rs3c3r3tp455w0rd with your own unique and strong password. Successfully running this should present you with output similar to the below:

MariaDB [(none)]> GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';\nQuery OK, 0 rows affected (0.00 sec)\n

In the example above, we have effectively declared that SeAT will be using the database as seat:s_p3rs3c3r3tp455w0rd@localhost/seat.

Finally, we will flush the database server privileges:

FLUSH PRIVILEGES;\n

That concludes the database server setup. You can exit the prompt with exit;

Note

Remember the password for the seat database user as we will need it later to configure SeAT.

"},{"location":"installation/manual_installation/#php","title":"PHP","text":"

Since SeAT is written primarily in PHP, we will need to install PHP packages. Ubuntu based systems can make use of the ondrej PPA which is a very popular repository used for specific PHP versions.

Depending on the version of Ubuntu you are using, a release specific repository URL should be used for the PPA. Select the tab applicable to your Ubuntu version and run the commands within.

Jammy 22.04Focal 20.04Bionic 18.04 
echo \"deb http://ppa.launchpad.net/ondrej/php/ubuntu jammy main\" >> /etc/apt/sources.list.d/php.list\necho \"deb-src http://ppa.launchpad.net/ondrej/php/ubuntu jammy main\" >> /etc/apt/sources.list.d/php.list\n
echo \"deb http://ppa.launchpad.net/ondrej/php/ubuntu focal main\" >> /etc/apt/sources.list.d/php.list\necho \"deb-src http://ppa.launchpad.net/ondrej/php/ubuntu focal main\" >> /etc/apt/sources.list.d/php.list\n
echo \"deb http://ppa.launchpad.net/ondrej/php/ubuntu bionic main\" >> /etc/apt/sources.list.d/php.list\necho \"deb-src http://ppa.launchpad.net/ondrej/php/ubuntu bionic main\" >> /etc/apt/sources.list.d/php.list\n

Next, we will have to download the new repositories GPG signing key and add it into our keychain

apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 4F4EA0AAE5267A6C\n

With the new repository configured, update the package lists with:

apt-get update\n

Finally, install the required PHP packages with:

apt-get install libpng-dev libfreetype6-dev libjpeg-dev\napt-get install openssl zip php8.2-bz2 php8.2-cli php8.2-curl php8.2-dom php8.2-gd php8.2-gmp php8.2-intl php8.2-mbstring php8.2-mysql php8.2-opcache php8.2-redis php8.2-zip\n
"},{"location":"installation/manual_installation/#redis","title":"Redis","text":"

SeAT makes use of Redis as a cache and message broker for the Queue back end. Installing it is really easy. Do it with:

apt-get install redis-server\n

Hint

By default, redis is making backup from its database - so it ensure integrity in case of failure. However, in certain condition, like power outage, this backup might be unprocessable and avoid redis to run.

Since we don't store anything critical in it, you may want to disable this. To do so, edit the configuration file using nano /etc/redis/redis.conf and search line appendonly no, change it for appendonly yes

If you are on a small server, You may also want to limit the part of memory used by redis (by default, it will consume all available memory). To do so, into the redis configuration file, search line # maxmemory <bytes> and change it for maxmemory xGB where x is the memory limit you want to set.

You might also need to start redis: 

systemctl enable redis-server.service\n

"},{"location":"installation/manual_installation/#seat-installation","title":"SeAT Installation","text":""},{"location":"installation/manual_installation/#prerequisites","title":"Prerequisites","text":"

Excellent progress! All of the operating system level requirements are now met and we are almost ready to install SeAT itself. The only thing that is outstanding is the package manager called composer as well as the git client. The combination of composer and git will let us download the SeAT source code from Github and install it locally.

"},{"location":"installation/manual_installation/#git","title":"Git","text":"

Install git with:

apt-get install git\n
"},{"location":"installation/manual_installation/#composer","title":"Composer","text":"

Next, install composer with:

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && hash -r\n

Thats it. Lets install SeAT! By default, we suggest you run SeAT from within /var/www/seat. As part of the installation, the seat directory will be created for us, but we will need to create /var/www for now as we have not yet configured the web server.

Create the www directory with:

mkdir -p /var/www\n

Next, cd to the new /var/www directory with:

cd /var/www\n
"},{"location":"installation/manual_installation/#seat-download","title":"SeAT Download","text":"

With all of the prerequisites installed as well as our www directory ready we can finally download SeAT. Do that with:

composer create-project eveseat/seat:5.0 --no-dev --no-interaction\n

Once the download is done, you should have seen output such as:

Writing lock file\nGenerating optimized autoload files\n> Illuminate\\Foundation\\ComposerScripts::postAutoloadDump\n> @php artisan package:discover\nDiscovered Package: darkaonline/l5-swagger\nDiscovered Package: eveseat/api\nDiscovered Package: eveseat/console\nDiscovered Package: eveseat/eveapi\nDiscovered Package: eveseat/notifications\nDiscovered Package: eveseat/services\nDiscovered Package: eveseat/web\nPackage manifest generated successfully.\n> @php artisan key:generate\nApplication key [base64:CmhqYNkaIcHo8nYC8LiEWa3U5/+BiTLih5dZftxlV2k=] set successfully.\n
"},{"location":"installation/manual_installation/#permissions","title":"Permissions","text":"

You may have noticed a warning about composer running as root. For now this can be safely ignored. Post the installation of the SeAT source code, we need to fix up the permissions of the downloaded files. Do that with:

chown -R www-data:www-data /var/www/seat\nchmod -R guo+w /var/www/seat/storage/\n

This will ensure that the web server, cron jobs and workers have access to the source code as well as logs.

"},{"location":"installation/manual_installation/#seat-setup","title":"SeAT Setup","text":"

With SeAT downloaded, we need to configure it. There are a number of configuration tasks needed. These include editing the applications .env file as well as running some commands that setup and seed the database. A configuration value reference can be found here.

"},{"location":"installation/manual_installation/#env-setup","title":".env setup","text":"

The first task would be to configure the applications database connection. Open the file located at /var/www/seat/.env with something like vi or nano and update the database options with your values. Typically, only the password would really need to be updated. If you are making use of an existing database somewhere else over the network, update the applicable fields such as DB_HOST accordingly.

DB_CONNECTION=mysql\nDB_HOST=127.0.0.1\nDB_PORT=3306\nDB_DATABASE=seat\nDB_USERNAME=seat\nDB_PASSWORD=s_p3rs3c3r3tp455w0rd # <-- this is the value you probably need to edit.\nDB_DEBUG=false\n
"},{"location":"installation/manual_installation/#database-migrations-and-seeds","title":"Database Migrations and Seeds","text":"

Next we need to publish the database migrations and web assets (such as JavaScript scripts and CSS Style sheets), run those migrations and finally seed the SeAT job schedule.

Publish the assets and database migrations with:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'\n

Run the database migrations with:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'\n

Seed the SeAT schedule with:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\\\Services\\\\Database\\\\Seeders\\\\PluginDatabaseSeeder'\n
"},{"location":"installation/manual_installation/#eve-sde-update","title":"EVE Sde Update","text":"

SeAT makes use of a number of tables from the EVE Static Data Exports. MariaDB conversions of this data is available at https://www.fuzzwork.co.uk/dump/ and used in SeAT.

To update to the latest SDE within SeAT, run:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde'\n
"},{"location":"installation/manual_installation/#supervisor","title":"Supervisor","text":"

The jobs ecosystem within SeAT requires a process supervisor to ensure that the job runner stays alive. The job runner itself is implemented using Laravel Horizon and is monitored using supervisord.

To configure the Horizon process monitor, first install supervisor:

apt-get install supervisor\n

Next, we will create a dedicated configuration file which will ask supervisor to keep an eye on Horizon. This file will live in /etc/supervisor/conf.d/seat.conf. Create this file with its recommended configuration with:

cat > /etc/supervisor/conf.d/seat.conf << EOL\n[program:seat]\ncommand=/usr/bin/php /var/www/seat/artisan horizon\nprocess_name = %(program_name)s-80%(process_num)02d\nstdout_logfile = /var/log/seat-80%(process_num)02d.log\nstdout_logfile_maxbytes=100MB\nstdout_logfile_backups=10\nnumprocs=1\ndirectory=/var/www/seat\nstopwaitsecs=600\nuser=www-data\nEOL\n

Finally, reload supervisor to apply the new configuration with the following command:

systemctl enable supervisor.service\n
"},{"location":"installation/manual_installation/#crontab","title":"Crontab","text":"

A crontab entry is needed for SeAT. While simple in implementation, this crontab entry simply helps the application invoke a job checker very minute. The actual schedule is stored within SeAT itself and managed entirely via the Web Interface.

To configure the crontab entry required for SeAT, run the following commands:

echo '* * * * * php /var/www/seat/artisan schedule:run >> /dev/null 2>&1' > /tmp/seat-crontab.tmp\n

Next, add this crontab for the www-data user with:

crontab -u www-data /tmp/seat-crontab.tmp\n

If you want to confirm that the crontab successfully installed, you can check it with crontab -u www-data -l.

"},{"location":"installation/manual_installation/#web-server","title":"Web Server","text":"

Almost there!

You almost made it to the end! Just one more step.

The SeAT web interface requires a web server to serve the HTML goodies it has. We highly recommend you to use nginx and will be covered in this document. You don't have to use it, so if you prefer something else, feel free.

"},{"location":"installation/manual_installation/#nginx-install","title":"Nginx Install","text":"

Together with an nginx installation we also need to install php-fpm to handle the PHP execution for us. Let's install nginx and php-fpm with:

apt-get install nginx php8.2-fpm\n
"},{"location":"installation/manual_installation/#nginx-configuration","title":"Nginx Configuration","text":"

With the webserver installed, we need to configure nginx to serve SeAT. For that, a configuration file needs to be created that will tell nginx where to find php-fpm as well as where the assets are for SeAT.

The configuration file will live at /etc/nginx/sites-available/seat. It can be created with the following command:

cat > /etc/nginx/sites-available/seat << EOL\nserver {\n    listen 80;\n    listen [::]:80;\n    # If you are hosting this instance on a domain, set that\n    # name here.\n    #server_name  seat.yourdomain.com;\n    # SeAT public directory. This is the only directory that\n    # should be exposed by the webserver. If one has to expose\n    # the parent directory then things like the .env file will\n    # be available for anyone to download.\n    root /var/www/seat/public;\n    index index.php;\n    location / {\n       try_files \\$uri \\$uri/ /index.php?\\$query_string;\n    }\n    # PHP-FPM configuration.\n    location ~ \\.php\\$ {\n       try_files \\$uri /index.php =404;\n       fastcgi_pass unix:/run/php/php8.2-fpm.sock;\n       fastcgi_param SCRIPT_FILENAME \\$document_root\\$fastcgi_script_name;\n       include fastcgi_params;\n    }\n    # Even though .htaccess rules mean nothing in the nginx\n    # world, prevent those from being downloaded anyways.\n    location ~ /\\.ht {\n       deny all;\n    }\n    # In case someone messes up, prevent .env files from\n    # being downloaded as well.\n    location ~ /\\.env {\n       deny all;\n    }\n}\nEOL\n

Warning

The code block above should not be copied directly into a file. It is a script and should be pasted directly into the linux terminal. It will create the nginx config for you. If you create the file yourself with the above content then the file will not be valid and you will receive errors from nginx.

The configuration file as is at /etc/nginx/sites-available/seat itself won't be loaded by nginx yet. Storing configuration files in a *sites-available* directory is simply a convention used to allow administrators to quickly add & remove sites if needed. To apply the changes made by the new configuration file it needs to be symlinked to a *sites-enabled* directory.

Let's symlink to the new configuration and drop the default one as a hardening exercise at the same time:

ln -s /etc/nginx/sites-available/seat /etc/nginx/sites-enabled/seat\nrm /etc/nginx/sites-enabled/default\n

Finally, reload nginx and php-fpm for the new changes to take affect:

systemctl restart nginx.service\nsystemctl restart php8.2-fpm.service\n
"},{"location":"installation/manual_installation/#esi-configuration","title":"ESI Configuration","text":"

As mentioned at the start of the guide, it is necessary for you to configure ESI. For instructions how to do this, please refer to the ESI Setup Guide.

Info

You may want to serve your SeAT installation over SSL (using HTTPS) - which is a recommanded behavior. There are many way to do it, you can have a look on Let's Encrypt which provide you valid certificates for free. Put an eye to their Certbot Documentation.

Success

You made it! Use a browser and browse to the IP address / hostname of your server to access SeAT!

"},{"location":"installation/requirements/","title":"Requirements","text":""},{"location":"installation/requirements/#requirements","title":"Requirements","text":""},{"location":"installation/requirements/#hardware-requirements","title":"Hardware Requirements","text":"

As far as hardware goes, there isn't really a hard and fast rule on what is needed. The more resources you make available, the faster API updates will occur. However, there are some minimum recommended specifications.

Info

Required CPU cores are indicative and may changes depending on your processor. They have been based on a one tier deployment (app, workers and database are hosted on the same server).

To improve accuracy regarding CPU requirements, we provide a Coremark value. Since Cloud providers like Azure and Google Cloud are providing their instance benchmark using this test, it should give you a more meaningful idea of what we are talking about.

Warning

If you intend to process a large amount of data, plan your storage accordingly. The SeAT database can grow incredibly quickly depending on the amount of tokens you process.

Due to high I/O traffic generated by SeAT, we recommand NVMe storage usage for best performances.

"},{"location":"installation/requirements/#up-to-25-characters","title":"Up to 25 characters","text":"Type Requirement CPU 2 virtual cores (Coremark 20 000+) Memory 2GB of RAM with a swap file Core Storage Space 1GB (tend to be stable) ESI Cache Storage Space 2GB (tend to grow with characters) Database Storage Space 5GB (tend to grow with characters and history)"},{"location":"installation/requirements/#up-to-500-characters","title":"Up to 500 characters","text":"Type Requirement CPU 2 virtual cores (Coremark 20 000+) Memory 4GB of RAM Core Storage Space 1GB (tend to be stable) ESI Cache Storage Space 5GB (tend to grow with characters) Database Storage Space 10GB (tend to grow with characters and history)"},{"location":"installation/requirements/#up-to-1-000-characters","title":"Up to 1 000 characters","text":"Type Requirement CPU 4 virtual cores (Coremark 40 000+) Memory 8GB of RAM Core Storage Space 1GB (tend to be stable) ESI Cache Storage Space 10GB (tend to grow with characters) Database Storage Space 20GB (tend to grow with characters and history)"},{"location":"installation/requirements/#more-than-1-000-characters","title":"More than 1 000 characters","text":"

If you plan to run SeAT for more than 1 000 characters, you will have to fine tune your installation and carefully monitoring it. At time this documentation is wrote, a standard character is queuing around 50 jobs per wave. Since all jobs are not doing the same thing, it's difficult to provide you accurate figures.

A single worker is consuming around 200 MB of memory. Most jobs are requiring less than 5% of CPU - however, a few of them need more than 20% of it. The more jobs you'll get, the more workers you'll need to process queue in less than 60 minutes.

Warning

With such installation, you shouldn't share SeAT server resources with other services. Also, you should consider deploying database on another server.

"},{"location":"installation/requirements/#software-requirements","title":"Software Requirements","text":""},{"location":"installation/requirements/#docker-environment","title":"Docker Environment","text":"

For Docker based installations, all you need is docker. If you already have it installed, check your current version with docker version.

Type Requirement Version Check Docker Docker: ^24.0 docker -v

Info

If you plan to deploy SeAT on a Windows host, you will need Docker for Windows

Warning

Do not install Docker directly from your distributions repositories. These are usually out of date. Instead, rather follow the steps provided on dockers official documentation

When considering a VPS provider, make sure you choose one that does not make use of OpenVZ or similar operating-system level virtualization technologies. These virtualization technologies limit you in terms of kernel access as they purely containerize an existing Linux installation.

For a successful docker installation, choose a provider that uses para-virtualized technologies such as KVM, VMWare or XEN allowing you full control to the instance (and therefor the kernel itself). Examples of such providers are Digital Ocean, Linode and Vultr.

"},{"location":"installation/requirements/#bare-metal-environment","title":"Bare metal Environment","text":"

Info

We consider \"bare metal\", any environment on which SeAT has been deployed manually (instead using containers).

If you plan to deploy SeAT on a Windows host, you will have to use Docker

Software version requirements are based on a minimum requirement.

Type Requirement State Check Operating System Linux (any distribution is suitable, however, Ubuntu tends to get more up-to-date packages on official repositories). Usually, running cat /etc/issue should give you a good idea. Architecture 64-bit only uname -p PHP PHP: ^8.3 including mysql, gd, bz2, intl, pcntl, gmp, openssl, zip, opcache and redis extensions php -v and php -i Database MariaDB: ^10.2.7 mysql -V Caching Service Redis redis-server -v Service Supervisor Supervisor : 3 supervisord -v Web Server NGinX or Apache nginx -v or httpd -v

Tip

In case you want to deploy SeAT with Apache as web server, plan to configure it with Fast CGI using php-fpm instead embedded php process. Doing it so will make you benefit of significant improved performances.

"},{"location":"installation/old_versions/docker_installation_seat_4/","title":"Docker Installation (4.x)","text":""},{"location":"installation/old_versions/docker_installation_seat_4/#docker","title":"Docker","text":"

Docker is ideally the installation route you want to go. Docker enables us to run SeAT on any platform capable of running docker itself (which includes Windows!). Additionally, upgrades and service maintenance are really low effort as you don't have to care about any dependencies. All of it is maintained within a docker stack and dockerhub.

Info

If you plan on running Docker on Windows, for the best performance it is suggested that you run Docker using the Windows Subsystem for Linux 2 (WSL2) backend, available starting in Windows 10/Windows Server 20H1 (build 2004) releases.

Hint

Before starting the installation process, be sure you read this complete document first. It will help you understand all of the steps from an installation process.

If you feel like docker might not be your cup of tea, checkout some of the other getting started guides that are available.

Warning

If you are using Docker on Windows, you will need to use the Manual Deployment option below.

Eve Application and ESI

SeAT used CCP's ESI service in order to retrieve EVE Online-related information. Before you can make any authenticated calls to ESI, you have to register a third-party EVE application on the developers portal. This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

"},{"location":"installation/old_versions/docker_installation_seat_4/#internal-container-setup-overview","title":"Internal Container Setup Overview","text":"

The setup for SeAT's docker installation orchestrated using docker-compose. With docker-compose, we can use a single docker-compose.yml file to define the entire stack complete with all of the dependencies required to run SeAT. A pre-built and recommended compose file (which is also used by the bootstrapping script) is hosted in the seat-docker repository here.

The previously mentioned compose file is really simple. A high-level overview of its contents is:

  • A single docker network called seat-network is defined. All containers are connected to this network and is used as the primary means for inter-container communications.
  • A single volume called mariadb-data is defined. This is the most important volume as it contains all of the database data. This is the one volume that you should configure a backup solution for!
  • Six services (or containers) are used within the SeAT docker stack. Three services use basic images pulled directly from Dockerhub and three others use a custom-built image, also hosted on DockerHub. The container images used are:
Image Name Image Repository mariadb:10 https://hub.docker.com/_/mariadb/ redis:5-alpine https://hub.docker.com/_/redis/ traefik:2.2 https://hub.docker.com/_/traefik eveseat/seat https://hub.docker.com/r/eveseat/seat
  • The environment is configured using a top-level .env file (not to be confused with the SeAT specific .env file.
  • Only two ports are exposed by default. Those are tcp/80 and tcp/443. These can be connected to in order to access the SeAT web interface.
  • All containers are configured to restart on failure, so if your server reboots or a container dies for whatever reason it should automatically start up again.
"},{"location":"installation/old_versions/docker_installation_seat_4/#seat-docker-installation","title":"SeAT Docker Installation","text":"

Depending on whether you already have docker and docker-compose already installed, you may choose how to start the installation. If you already have the required tooling installed and running their latest versions, all you need to do is download the latest docker-compose.yml and .env files to get started.

"},{"location":"installation/old_versions/docker_installation_seat_4/#automated-setup-script","title":"Automated Setup Script","text":"

If you do not have the required software installed yet, consider running the bootstrap script that will check for docker and docker-compose, install it and start the SeAT stack up for you. The script can be run with:

bash <(curl -fsSL https://git.io/get-seat)\n

Once the script is finished, you can skip to the monitoring the stack section of this guide.

If you don't want to run this script, follow along in the next section of this guide.

"},{"location":"installation/old_versions/docker_installation_seat_4/#manual-deployment","title":"Manual Deployment","text":""},{"location":"installation/old_versions/docker_installation_seat_4/#docker-download","title":"Docker Download","text":"

If you do not have docker, install it now with the following command as root:

sh <(curl -fsSL get.docker.com)\n

If you are on Windows, download and install Docker Desktop.

"},{"location":"installation/old_versions/docker_installation_seat_4/#docker-compose-download","title":"Docker-compose Download","text":"

If you do not have docker-compose, install it now with the following command as root (Docker Compose is included with Docker Desktop on Windows):

# Downloads docker-compose\ncurl -L https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose\n\n# Makes docker-compose executable\nchmod +x /usr/local/bin/docker-compose\n
"},{"location":"installation/old_versions/docker_installation_seat_4/#docker-compose-working-directory","title":"Docker compose working directory","text":"

With docker and docker-compose ready, create yourself a directory in /opt with mkdir -p /opt/seat-docker and cd to it. Remember this directory as you will need to come back to it often.

On Windows, create the C:\\seat-docker directory with mkdir C:\\seat-docker and cd to it.

"},{"location":"installation/old_versions/docker_installation_seat_4/#seat-docker-composeyml-and-env-file","title":"SeAT docker-compose.yml and .env File","text":"

Then, download the docker-compose.yml file with:

LinuxWindows 
curl -fsSL https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -o docker-compose.yml\n
Invoke-WebRequest -Uri https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -OutFile docker-compose.yml\n

Next, download the docker .env file with:

LinuxWindows 
curl -fsSL https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -o .env\n
Invoke-WebRequest -Uri https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -OutFile .env\n

Next, we will generate a unique application key - this is used internally for encryption:

LinuxWindows 
sed -i -- 's/APP_KEY=insecure/APP_KEY='$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c32 ; echo '')'/g' .env\n
$appkey = (-join ((65..90) + (97..122) | Get-Random -Count 32 | % {[char]$_})); (Get-Content .env -Raw) -replace \"APP_KEY=insecure\", \"APP_KEY=$appkey\" | Set-Content .env\n
"},{"location":"installation/old_versions/docker_installation_seat_4/#seat-docker-configuration","title":"SeAT docker configuration","text":"

Open up the .env file in a text editor and fill in a few of the configuration items needed.

TRAEFIK_DOMAIN should be set to the base domain your installation lives on. SEAT_SUBDOMAIN sould be the subdomain for the SeAT web UI. eg: seat.domain.local

For TLS configuration, you need to set the TRAEFIK_ACME_EMAIL value, and then in the docker-compose.yml file uncomment the labels that relating to certResolver. They typically look like this: traefik.http.routers.api.tls.certResolver=primary. Finally, create an ACME configuration file with:

mkdir acme\ntouch acme/acme.json\nchmod 600 acme/acme.json\n

Info

SeAT docker template is shipped with Traefik to hide your container behind a proxy and securing traffic up to it. In case you want to manage traffic proxying and certification on your own, you can disable traefik container from the stack by adding # [front of lines] from the docker-compose.yml file.

Warning

The location of the docker-compose.yml and .env files are important. You need to cd back to the directory where these are stored in order to be able to execute commands for this stack at a later stage.

Also, be sure you provide a valid e-mail address as it will be used to register your account against Let's Encrypt. For those unfamiliar with this, it's CA that provides valid certificates for free.

"},{"location":"installation/old_versions/docker_installation_seat_4/#esi-configuration","title":"ESI Configuration","text":"

As mentioned at the start of the guide, it is necessary for you to configure ESI. For instructions on how to do this, please refer to the ESI Setup Guide.

With the configuration files ready, start up the stack with:

docker-compose up -d\n
"},{"location":"installation/old_versions/docker_installation_seat_4/#monitoring-the-stack","title":"Monitoring the Stack","text":"

Knowing what is going on inside of your containers is crucial to understanding how everything is running as well as useful when debugging any problems that may occur. While the containers are starting up or have been running for a while, you can always cd to the directory where your docker-compose.yml file lives and run the logs command to see the output of all of the containers in the stack. For example:

cd /opt/seat-docker\ndocker-compose logs --tail 10 -f\n

These commands will cd to the directory containing the stacks docker-compose.yml file and run the logs command, showing the last 10 log entries and then printing new ones as they arrive.

"},{"location":"installation/old_versions/docker_installation_seat_4/#configuration-changes","title":"Configuration Changes","text":"

All of the relevant configuration lives inside the .env file, next to your docker-compose.yml file. Modify their values by opening it in a text editor, making the appropriate changes, and saving it again. Once that is done, run docker-compose up -d again to restart the container environment.

Success

You made it! Use a browser and browse to the domain / subdomain of your server to access SeAT!

"},{"location":"installation/old_versions/manual_installation_seat_4/","title":"Manual Installation (4.x)","text":""},{"location":"installation/old_versions/manual_installation_seat_4/#manual-installation","title":"Manual Installation","text":"

This guide attempts to explain how to manually install SeAT onto an Ubuntu Server. A small amount of Linux experience is preferred when it comes to this guide, although it is not entirely mandatory.

Info

This guide has been written targetting Ubuntu. However, you can use it to deploy SeAT on any linux distribution. Just be sure you adapt commands to targetted distribution (mostly those related to the package manager).

Hint

Before starting to do anything, be sure you read the complete workflow once. It will help you to understand all steps from the installation process.

Eve Application and ESI

SeAT consumes CCP's ESI service in order to retrieve EVE Online related information. Before you can make any authenticated calls to ESI, you have to register a third party EVE application on the developers portal. This is an absolute must for SeAT to be of any use. The configuration of this step is covered in a later stage of the documentation.

"},{"location":"installation/old_versions/manual_installation_seat_4/#getting-started","title":"Getting started","text":"

We are going to assume you have root access to a fresh Ubuntu Server. Typically access is gained via SSH. All of the below commands are to be entered in the SSH terminal session for the installation & configuration of SeAT. If the server you want to install SeAT on is being used for other things too (such as hosting MySQL databases and or websites), then please keep that in mind while following this guide.

Packages are installed using the aptitude package manager as the root user.

"},{"location":"installation/old_versions/manual_installation_seat_4/#os-installation","title":"OS Installation","text":""},{"location":"installation/old_versions/manual_installation_seat_4/#operating-system","title":"Operating System","text":"

Before we get to installing SeAT, lets ensure that your operating system is up to date. We can do that with basics :

  • apt-get update to refresh the repositories cache.
  • apt-get full-upgrade to update any installed packages.
  • reboot in order to ensure any updated software is the current running version.
  • apt-get autoremove (after the reboot) to cleanup any unneeded packages.
"},{"location":"installation/old_versions/manual_installation_seat_4/#database","title":"Database","text":"

SeAT relies heavily on a database to function. Everything it learns is stored here, along with things such as user accounts for your users. It comes without saying that database security is a very important aspect too. So, ensure that you choose very strong passwords for your installation where required.

This document describes using MariaDB, but you can use MySQL as well. Just double check the requirements.

We need to ensure that we have the latest MariaDB installed. To help with this, MariaDB provides an official repository to get the latest versions. Let's add this repository with:

curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | bash\n

With the repository now setup, lets install the database server:

Warning

During the installation, you may be asked to set a password for the root MariaDB user account. Make sure you set a long, strong password and remember it. It will be needed for the next step.

apt-get install mariadb-server\n

Next, we are going to secure the database server by removing anonymous access and setting a root password (if you have not been prompted for it yet).

Note

The database root password should not be confused with the operating systems root passwords. They are both completely different. They should also not have the same password.

To secure the database, run:

mysql_secure_installation\n

This will ask you a series of questions where you should generally just answer yes to. If you already set a root password in the previous step then you dont have to set it again, otherwise, make sure you choose a long, strong password for the root account. An example run is shown below:

[...]\nEnter current password for root (enter for none):  IF ONE WAS SET, IGNORE THIS\nOK, successfully used password, moving on...\n\n[...]\nSet root password? [Y/n] y\nNew password:             SET A STRONG PASSWORD HERE\nRe-enter new password:    SET A STRONG PASSWORD HERE\nPassword updated successfully!\nReloading privilege tables..\n ... Success!\n\n[...]\nRemove anonymous users? [Y/n] y\n ... Success!\n\n[...]\nDisallow root login remotely? [Y/n] y\n ... Success!\n\n[...]\nRemove test database and access to it? [Y/n] y\n\n[...]\nReload privilege tables now? [Y/n] y\n ... Success!\n\n[...]\n

That concludes the installation of the database server and securing it.

Next, we need to create an actual user and database for SeAT to use on the newly installed server. To do this we use the mysql command line client and enter a few commands as the root user to create the database and the user that will be accessing the server. Let get to it.

Fire up the mysql client as root by running:

mysql -uroot -p\n

This will prompt you for a password. Use the password you configured for the root account when we ran mysql_secure_installation. This will most probably be the last time you need to use this password :)

If the password was correct, you should see a prompt similar to the one below:

root@ubuntu:~# mysql -uroot -p\nEnter password:\nWelcome to the MariaDB monitor.  Commands end with ; or \\g.\nYour MariaDB connection id is 16\nCopyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nMariaDB [(none)]>\n

Create a new database for SeAT to use with:

create database seat;\n

The output should be similar to the below:

MariaDB [(none)]> create database seat;\nQuery OK, 1 row affected (0.00 sec)\n

Next, we need to create the user that SeAT itself will use to connect and use the new seat database:

GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';\n

Of course, you need to replace s_p3rs3c3r3tp455w0rd with your own unique and strong password. Successfully running this should present you with output similar to the below:

MariaDB [(none)]> GRANT ALL ON seat.* to seat@localhost IDENTIFIED BY 's_p3rs3c3r3tp455w0rd';\nQuery OK, 0 rows affected (0.00 sec)\n

In the example above, we have effectively declared that SeAT will be using the database as seat:s_p3rs3c3r3tp455w0rd@localhost/seat.

Finally, we will flush the database server privileges:

FLUSH PRIVILEGES;\n

That concludes the database server setup. You can exit the prompt with exit;

Note

Remember the password for the seat database user as we will need it later to configure SeAT.

"},{"location":"installation/old_versions/manual_installation_seat_4/#php","title":"PHP","text":"

Since SeAT is written primarily in PHP, we will need to install PHP packages. Ubuntu based systems can make use of the ondrej PPA which is a very popular repository used for specific PHP versions.

Depending on the version of Ubuntu you are using, a release specific repository URL should be used for the PPA. Select the tab applicable to your Ubuntu version and run the commands within.

Bionic 18.04Focal 20.04 
echo \"deb http://ppa.launchpad.net/ondrej/php/ubuntu bionic main\" >> /etc/apt/sources.list.d/php.list\necho \"deb-src http://ppa.launchpad.net/ondrej/php/ubuntu bionic main\" >> /etc/apt/sources.list.d/php.list\n
echo \"deb http://ppa.launchpad.net/ondrej/php/ubuntu focal main\" >> /etc/apt/sources.list.d/php.list\necho \"deb-src http://ppa.launchpad.net/ondrej/php/ubuntu focal main\" >> /etc/apt/sources.list.d/php.list\n

Next, we will have to download the new repositories GPG signing key and add it into our keychain

apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 4F4EA0AAE5267A6C\n

With the new repository configured, update the package lists with:

apt-get update\n

Finally, install the required PHP packages with:

apt-get install libpng-dev libfreetype6-dev libjpeg-dev\napt-get install curl openssl zip php7.3-bz2 php7.3-cli php7.3-curl php7.3-dom php7.3-gd php7.3-gmp php7.3-intl php7.3-mbstring php7.3-mysql php7.3-opcache php7.3-redis php7.3-zip\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#redis","title":"Redis","text":"

SeAT makes use of Redis as a cache and message broker for the Queue back end. Installing it is really easy. Do it with:

apt-get install redis-server\n

Hint

By default, redis is making backup from its database - so it ensure integrity in case of failure. However, in certain condition, like power outage, this backup might be unprocessable and avoid redis to run.

Since we don't store anything critical in it, you may want to disable this. To do so, edit the configuration file using nano /etc/redis/redis.conf and search line appendonly no, change it for appendonly yes

If you are on a small server, You may also want to limit the part of memory used by redis (by default, it will consume all available memory). To do so, into the redis configuration file, search line # maxmemory <bytes> and change it for maxmemory xGB where x is the memory limit you want to set.

"},{"location":"installation/old_versions/manual_installation_seat_4/#seat-installation","title":"SeAT Installation","text":""},{"location":"installation/old_versions/manual_installation_seat_4/#prerequisites","title":"Prerequisites","text":"

Excellent progress! All of the operating system level requirements are now met and we are almost ready to install SeAT itself. The only thing that is outstanding is the package manager called composer as well as the git client. The combination of composer and git will let us download the SeAT source code from Github and install it locally.

"},{"location":"installation/old_versions/manual_installation_seat_4/#git","title":"Git","text":"

Install git with:

apt-get install git\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#composer","title":"Composer","text":"

Next, install composer with:

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && hash -r\n

Thats it. Lets install SeAT! By default, we suggest you run SeAT from within /var/www/seat. As part of the installation, the seat directory will be created for us, but we will need to create /var/www for now as we have not yet configured the web server.

Create the www directory with:

mkdir -p /var/www\n

Next, cd to the new /var/www directory with:

cd /var/www\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#seat-download","title":"SeAT Download","text":"

With all of the prerequisites installed as well as our www directory ready we can finally download SeAT. Do that with:

composer create-project eveseat/seat --no-dev --no-interaction\n

Once the download is done, you should have seen output such as:

Writing lock file\nGenerating optimized autoload files\n> Illuminate\\Foundation\\ComposerScripts::postAutoloadDump\n> @php artisan package:discover\nDiscovered Package: darkaonline/l5-swagger\nDiscovered Package: eveseat/api\nDiscovered Package: eveseat/console\nDiscovered Package: eveseat/eveapi\nDiscovered Package: eveseat/notifications\nDiscovered Package: eveseat/services\nDiscovered Package: eveseat/web\nPackage manifest generated successfully.\n> @php artisan key:generate\nApplication key [base64:CmhqYNkaIcHo8nYC8LiEWa3U5/+BiTLih5dZftxlV2k=] set successfully.\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#permissions","title":"Permissions","text":"

You may have noticed a warning about composer running as root. For now this can be safely ignored. Post the installation of the SeAT source code, we need to fix up the permissions of the downloaded files. Do that with:

chown -R www-data:www-data /var/www/seat\nchmod -R guo+w /var/www/seat/storage/\n

This will ensure that the web server, cron jobs and workers have access to the source code as well as logs.

"},{"location":"installation/old_versions/manual_installation_seat_4/#seat-setup","title":"SeAT Setup","text":"

With SeAT downloaded, we need to configure it. There are a number of configuration tasks needed. These include editing the applications .env file as well as running some commands that setup and seed the database. A configuration value reference can be found here.

"},{"location":"installation/old_versions/manual_installation_seat_4/#env-setup","title":".env setup","text":"

The first task would be to configure the applications database connection. Open the file located at /var/www/seat/.env with something like vi or nano and update the database options with your values. Typically, only the password would really need to be updated. If you are making use of an existing database somewhere else over the network, update the applicable fields such as DB_HOST accordingly.

DB_CONNECTION=mysql\nDB_HOST=127.0.0.1\nDB_PORT=3306\nDB_DATABASE=seat\nDB_USERNAME=seat\nDB_PASSWORD=s_p3rs3c3r3tp455w0rd # <-- this is the value you probably need to edit.\nDB_DEBUG=false\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#database-migrations-and-seeds","title":"Database Migrations and Seeds","text":"

Next we need to publish the database migrations and web assets (such as JavaScript scripts and CSS Style sheets), run those migrations and finally seed the SeAT job schedule.

Publish the assets and database migrations with:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'\n

Run the database migrations with:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'\n

Seed the SeAT schedule with:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\\\Console\\\\database\\\\seeds\\\\ScheduleSeeder'\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#eve-sde-update","title":"EVE Sde Update","text":"

SeAT makes use of a number of tables from the EVE Static Data Exports. MySQL conversions of this data is available at https://www.fuzzwork.co.uk/dump/ and used in SeAT.

To update to the latest SDE within SeAT, run:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde'\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#supervisor","title":"Supervisor","text":"

The jobs ecosystem within SeAT requires a process supervisor to ensure that the job runner stays alive. The job runner itself is implemented using Laravel Horizon and is monitored using supervisord.

To configure the Horizon process monitor, first install supervisor:

apt-get install supervisor\n

Next, we will create a dedicated configuration file which will ask supervisor to keep an eye on Horizon. This file will live in /etc/supervisor/conf.d/seat.conf. Create this file with its recommended configuration with:

cat > /etc/supervisor/conf.d/seat.conf << EOL\n[program:seat]\ncommand=/usr/bin/php /var/www/seat/artisan horizon\nprocess_name = %(program_name)s-80%(process_num)02d\nstdout_logfile = /var/log/seat-80%(process_num)02d.log\nstdout_logfile_maxbytes=100MB\nstdout_logfile_backups=10\nnumprocs=1\ndirectory=/var/www/seat\nstopwaitsecs=600\nuser=www-data\nEOL\n

Finally, reload supervisor to apply the new configuration with the following command:

systemctl restart supervisor.service\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#crontab","title":"Crontab","text":"

A crontab entry is needed for SeAT. While simple in implementation, this crontab entry simply helps the application invoke a job checker very minute. The actual schedule is stored within SeAT itself and managed entirely via the Web Interface.

To configure the crontab entry required for SeAT, run the following commands:

echo '* * * * * php /var/www/seat/artisan schedule:run >> /dev/null 2>&1' > /tmp/seat-crontab.tmp\n

Next, add this crontab for the www-data user with:

crontab -u www-data /tmp/seat-crontab.tmp\n

If you want to confirm that the crontab successfully installed, you can check it with crontab -u www-data -l.

"},{"location":"installation/old_versions/manual_installation_seat_4/#web-server","title":"Web Server","text":"

Almost there!

You almost made it to the end! Just one more step.

The SeAT web interface requires a web server to serve the HTML goodies it has. We highly recommend you to use nginx and will be covered in this document. You don't have to use it, so if you prefer something else, feel free.

"},{"location":"installation/old_versions/manual_installation_seat_4/#nginx-install","title":"Nginx Install","text":"

Together with an nginx installation we also need to install php-fpm to handle the PHP execution for us. Let's install nginx and php-fpm with:

apt-get install nginx php7.3-fpm\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#nginx-configuration","title":"Nginx Configuration","text":"

With the webserver installed, we need to configure nginx to serve SeAT. For that, a configuration file needs to be created that will tell nginx where to find php-fpm as well as where the assets are for SeAT.

The configuration file will live at /etc/nginx/sites-available/seat. It can be created with the following command:

cat > /etc/nginx/sites-available/seat << EOL\nserver {\n    listen 80;\n    listen [::]:80;\n    # If you are hosting this instance on a domain, set that\n    # name here.\n    #server_name  seat.yourdomain.com;\n    # SeAT public directory. This is the only directory that\n    # should be exposed by the webserver. If one has to expose\n    # the parent directory then things like the .env file will\n    # be available for anyone to download.\n    root /var/www/seat/public;\n    index index.php;\n    location / {\n       try_files \\$uri \\$uri/ /index.php?\\$query_string;\n    }\n    # PHP-FPM configuration.\n    location ~ \\.php\\$ {\n       try_files \\$uri /index.php =404;\n       fastcgi_pass unix:/run/php/php7.3-fpm.sock;\n       fastcgi_param SCRIPT_FILENAME \\$document_root\\$fastcgi_script_name;\n       include fastcgi_params;\n    }\n    # Even though .htaccess rules mean nothing in the nginx\n    # world, prevent those from being downloaded anyways.\n    location ~ /\\.ht {\n       deny all;\n    }\n    # In case someone messes up, prevent .env files from\n    # being downloaded as well.\n    location ~ /\\.env {\n       deny all;\n    }\n}\nEOL\n

Warning

The code block above should not be copied directly into a file. It is a script and should be pasted directly into the linux terminal. It will create the nginx config for you. If you create the file yourself with the above content then the file will not be valid and you will receive errors from nginx.

The configuration file as is at /etc/nginx/sites-available/seat itself won't be loaded by nginx yet. Storing configuration files in a *sites-available* directory is simply a convention used to allow administrators to quickly add & remove sites if needed. To apply the changes made by the new configuration file it needs to be symlinked to a *sites-enabled* directory.

Let's symlink to the new configuration and drop the default one as a hardening exercise at the same time:

ln -s /etc/nginx/sites-available/seat /etc/nginx/sites-enabled/seat\nrm /etc/nginx/sites-enabled/default\n

Finally, reload nginx and php-fpm for the new changes to take affect:

systemctl restart nginx.service\nsystemctl restart php7.3-fpm.service\n
"},{"location":"installation/old_versions/manual_installation_seat_4/#esi-configuration","title":"ESI Configuration","text":"

As mentioned at the start of the guide, it is necessary for you to configure ESI. For instructions how to do this, please refer to the ESI Setup Guide.

Info

You may want to serve your SeAT installation over SSL (using HTTPS) - which is a recommanded behavior. There are many way to do it, you can have a look on Let's Encrypt which provide you valid certificates for free. Put an eye to their Certbot Documentation.

Success

You made it! Use a browser and browse to the IP address / hostname of your server to access SeAT!

"},{"location":"upgrading/from_seat_1_0/","title":"From SeAT 1.0","text":""},{"location":"upgrading/from_seat_1_0/#seat-10-to-20","title":"SeAT 1.0 to 2.0","text":"

The upgrade path from SeAT 1.x to SeAT 2.0 requires some manual work. This is mainly due to the number of fundamental changes that were made in the SeAT 2.x release.

"},{"location":"upgrading/from_seat_1_0/#notes-on-the-upgrade","title":"Notes on the upgrade","text":"

The way SeAT is structured has not changed much since its version 1x days. The biggest change is a Laravel framework upgrade to version 5.3. This introduced a new base layout for the application which is why the manual upgrade is needed.

The upgrade process has a large amount of database migrations that need to run so grab a coffee depending on how big your database is!

"},{"location":"upgrading/from_seat_1_0/#requirements","title":"Requirements","text":"
  • SeAT 2.0 requires PHP 7.0. At the time of writing this document, PHP 7.1 is not supported due to bug in PhealNG (the component SeAT uses to talk to the EVE API).
  • MySQL 5.7 is recommended but not required.
  • A database backup is an absolute must. Everything in SeAT can be recovered is some way or form except for your database. Make 100% sure you backed this up before proceeding with the upgrade!
  • Take note of where SeAT is installed. This is usually in /var/www/seat.
"},{"location":"upgrading/from_seat_1_0/#upgrade-procedure","title":"Upgrade procedure","text":""},{"location":"upgrading/from_seat_1_0/#preparation","title":"Preparation","text":"

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely). Its therefore recommended that you start by putting SeAT into maintenance mode before starting the upgrade. Do this by running the following command in your SeAT path.

$ cd /var/www/seat\n$ php artisan down\n

You should see the message Application is now in maintenance mode..

"},{"location":"upgrading/from_seat_1_0/#backups","title":"Backups","text":"
  • Make a backup of your SeAT database and store it somewhere safe! Do not skip this step!
  • In your SeAT directory, make a copy of the .env file. This file contains all of your SeAT configuration. These values are needed to reconnect to the database once SeAT 2.0 is installed.
"},{"location":"upgrading/from_seat_1_0/#php-7","title":"Php 7","text":"

Install PHP7 if you don't have it already. You can check your PHP version by running php -v:

$ php -v\nPHP 7.0.14 (cli) (built: Dec  7 2016 10:25:25) ( NTS )\nCopyright (c) 1997-2016 The PHP Group\nZend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies\n
"},{"location":"upgrading/from_seat_1_0/#get-the-new-code","title":"Get the new code","text":"

SeAT 2.0 can be installed in exactly the same place as where you had your v1.x installation. If you reuse this path then no webserver re-configuration will be needed. We will move the old installation out of the way, and install SeAT 2.0. To do this, run the following commands:

  • First, move the old installation out of the way:
$ cd /var/www\n$ mv seat seat.old\n

You can double check that this was successful by running ls and ensuring that there is a folder named seat.old now.

  • Next, get the new SeAT code by running composer create-project eveseat/seat seat --no-dev:
$ cd /var/www\n$ composer create-project eveseat/seat seat --no-dev\nInstalling eveseat/seat (2.0.0)\n- Installing eveseat/seat (2.0.0)\nLoading from cache\n\nCreated project in seat\n> php -r \"file_exists('.env') || copy('.env.example', '.env');\"\nLoading composer repositories with package information\nUpdating dependencies\n\n[ ... snip ... ]\n
"},{"location":"upgrading/from_seat_1_0/#publish-the-assets","title":"Publish the assets","text":"

Next, we need to publish the new SeAT 2.0 CSS & Javascript and database migrations. This can be done with php artisan vendor:publish --force.

"},{"location":"upgrading/from_seat_1_0/#reconfigure-env-file","title":"Reconfigure .env file","text":"

With the new code ready to use, the next thing that is required is to reconnect the database. Remember that .env file you backed up earlier? Refer to it for the values needed in the newly installed env file that can be found at /var/www/seat/.env.

Important keys to populate with the correct values are:

DB_HOST=\nDB_PORT=\nDB_DATABASE=\nDB_USERNAME=\nDB_PASSWORD=\n

SeAT 2.0 introduced new configuration items in the .env that you can review. There is also the option to configure Supervisor & SeAT integration, which can be done by following the admin guide titled SeAT & Supervisor Integration.

"},{"location":"upgrading/from_seat_1_0/#run-migrations","title":"Run migrations","text":"

With the database reconnected, its time to run the migrations for SeAT 2.0. This is the part that may take some time, depending on how big your database is.

To run the migrations, make sure you are still in your seat path (/var/www/seat) and run php artisan migrate:

$ cd /var/www/seat\n$ php artisan migrate\n

You will see a bunch of messages and eventually your shell prompt again, indicating that it has completed. If you receive errors here, double check that you have entered the correct database settings in the .env file previously mentioned.

"},{"location":"upgrading/from_seat_1_0/#database-seeders","title":"Database seeders","text":"

With the database migration complete, its time to seed it with some of the static data SeAT needs. Do this with the following commands:

php artisan db:seed --class=Seat\\\\Notifications\\\\database\\\\seeds\\\\ScheduleSeeder\nphp artisan db:seed --class=Seat\\\\Services\\\\database\\\\seeds\\\\NotificationTypesSeeder\nphp artisan db:seed --class=Seat\\\\Services\\\\database\\\\seeds\\\\ScheduleSeeder\n
"},{"location":"upgrading/from_seat_1_0/#update-worker-jobs","title":"Update worker jobs","text":"

The Laravel 5.3 upgrade in SeAT changed the way worker jobs are started. You can edit the command used to start a worker in your seat.conf file in supervisor. Normally, this file will be somewhere like in /etc/supervisor/conf.d/.

The only line you really need to edit is the one that starts with command, replacing it with:

command=/usr/bin/php /var/www/seat/artisan queue:work --queue=high,medium,low,default --tries 1 --timeout=86100\n

A full block for SeAT 2.0 should therefore be:

[program:seat]\ncommand=/usr/bin/php /var/www/seat/artisan queue:work --queue=high,medium,low,default --tries 1 --timeout=86100\nprocess_name = %(program_name)s-80%(process_num)02d\nstdout_logfile = /var/log/seat-80%(process_num)02d.log\nstdout_logfile_maxbytes=100MB\nstdout_logfile_backups=10\nnumprocs=4\ndirectory=/var/www/seat\nstopwaitsecs=600\nuser=www-data\n

Note

Keep in mind the user value and the path to artisan should be correct. Update them to the correct values of you made changes to the defaults. The user value differs many times based on Linux distribution too!

"},{"location":"upgrading/from_seat_1_0/#finishing-off","title":"Finishing off","text":"

With all of that done, bring your application back up with php artisan up and start the supervisor workers again. Watch the logs for any errors in case things have not gone as expected. If you need any help, feel free to join the Slack channel details in the Contact page on the left.

"},{"location":"upgrading/from_seat_2_0/","title":"From SeAT 2.0","text":""},{"location":"upgrading/from_seat_2_0/#seat-20-to-30","title":"SeAT 2.0 to 3.0","text":"

The upgrade path from SeAT 2.x to SeAT 3.0 requires some manual work. This is mainly due to the number of fundamental database changes that were made in SeAT 3.x.

"},{"location":"upgrading/from_seat_2_0/#notes-on-the-upgrade","title":"Notes on the upgrade","text":"

Most of the database has been revamped to match ESI models. Therefore, we can't offer you a simple update as we do for minor patches. However, once migrated, updates can be done as per usual.

The process described bellow handles data conversion between the SeAT 2.x structure and SeAT 3.x one.

"},{"location":"upgrading/from_seat_2_0/#requirements","title":"Requirements","text":"
  • Check SeAT 3.0 Requirements
  • A database backup is an absolute must. Everything in SeAT can be recovered is some way or form except for your database. Make 100% sure you backed this up before proceeding with the upgrade!
  • Enough storage space to contains SeAT 2, SeAT 3, a backup of SeAT 2 database and a backup of SeAT 3 database.
  • Take note of where SeAT 2 is installed. This is usually in /var/www/seat.
"},{"location":"upgrading/from_seat_2_0/#upgrade-procedure","title":"Upgrade procedure","text":""},{"location":"upgrading/from_seat_2_0/#preparation","title":"Preparation","text":"

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely). Its therefore recommended that you start by putting SeAT into maintenance mode before starting the upgrade. Do this by running the following command in your SeAT path. 

php artisan down\n

If you are running this migration after CCP killed the XML API then there is probably no risk of the updaters doing anything useful anyways :D

"},{"location":"upgrading/from_seat_2_0/#backups","title":"Backups","text":"
  • Make a backup of your SeAT database and store it somewhere safe! Do not skip this step!
  • In your SeAT directory, make a copy of the .env file. This file contains all of your SeAT configuration. These values may be useful in case of failure.
"},{"location":"upgrading/from_seat_2_0/#installing-seat-30","title":"Installing SeAT 3.0","text":"

Rename the current SeAT directory from /var/www/seat to /var/www/seat2. You don't have to update any config since we will only use the command line for the process. mv /var/www/seat /var/www/seat2

Follow standard installation instructions for SeAT 3.0.

Warning

You need to keep the current SeAT 2.0 installed in order to migrate data to a newly installed 3.0 instance. It doesn't have to be reachable from internet though since we will only use the command line for the process.

"},{"location":"upgrading/from_seat_2_0/#installing-the-migrator-package-on-seat-20","title":"Installing the migrator package on SeAT 2.0","text":"
  • Move to your SeAT 2.0 installation directory (should be /var/www/seat2 - unless you changed it)
  • Add the package called seat-migrator using composer require warlof/seat-migrator
  • Edit the app.php file inside the config folder by appending Warlof\\Seat\\Migrator\\MigratorServiceProvider::class, to the end of providers array.
  • Once done, publish the package files using php artisan vendor:publish --force
  • Run migration scripts with php artisan migrate
  • Finally, run php artisan seat:migrator:upgrade and follow the wizard

At the end of the process, you will have most of your data transferred into the specified SeAT 3.0 database. Next, you can remove the seat2 directory with rm -R /var/www/seat2 and the old database.

Enjoy SeAT 3.0

Note

In case of any troubles, the migrator package did a backup before starting the migration process. The output is specified in the prompt while it is being done, but you will also find it in /var/www/seat2/storage/backup.

"},{"location":"upgrading/general/","title":"General","text":""},{"location":"upgrading/general/#general-upgrades","title":"General Upgrades","text":"

As with anything, it is a very good idea to have backups ready before attempting any upgrades. In the case of SeAT, the most important component needs to be backed up is the SeAT database. Should something go wrong, then you can simply re-install SeAT, restore the database, and you should be good to go.

"},{"location":"upgrading/general/#docker-installation","title":"Docker installation","text":"

As expected, updates for SeAT are deployed via images on the GitHub Container Registry. Every package version release will automatically start the build process to generate a new docker image. This means updates are super simple in the docker world. To update your instance, simply run:

SeAT 4.xSeAT 5.x - TraefikSeAT 5.x - Proxy 
# Update to the latest dockerhub images\ndocker-compose pull\n\n# Take the stack down\ndocker-compose down\n\n# Bring the stack back up\ndocker-compose up -d\n\n# Cleanup any dangling images\ndocker image prune -f\n
# Update to the latest dockerhub images\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml pull\n\n# Take the stack down\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml down\n\n# Bring the stack back up\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d\n\n# Cleanup any dangling images\ndocker image prune -f\n
# Update to the latest dockerhub images\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml pull\n\n# Take the stack down\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml down\n\n# Bring the stack back up\ndocker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d\n\n# Cleanup any dangling images\ndocker image prune -f\n

Better safe then sorry

Always perform a database backup of your database before doing an update. Always.

"},{"location":"upgrading/general/#blade-installation","title":"Blade installation","text":"
  • Ensure that you are in the path where you installed. By default this should be /var/www/seat.
  • Cut jobs processing.
supervisorctl stop all\n
  • Put your application into maintenance mode. This will ensure that no request from the outside will hit your applications logic, and also help you perform an upgrade uninterrupted. Do this with:
php artisan down\n
  • Its a good thing to update composer itself. This is not a hard requirement, but definitely recommended. Do this with:
composer self-update\n
  • The next thing to do is get the latest SeAT packages. The below example adds the --no-dev argument as these packages are generally not needed in production. Upgrade the packages with:
composer update --no-dev\n
  • With the packages upgraded, we can now publish any new migrations/assets/configs. This can be done with:
php artisan vendor:publish --force --all\n
  • Once the needed files are published, run any new/outstanding migrations with:
php artisan migrate\n
  • With the migrations done, run the seeders to update any static data:
php artisan db:seed --class=Seat\\\\Console\\\\database\\\\seeds\\\\ScheduleSeeder\n
  • Finally, we can simply bring our application back out of maintenance mode with:
php artisan up\n
  • Prune job queue, this will prevent already queued jobs to use old codebase
php artisan cache:clear\n
  • Renew cached configuration and routes
php artisan config:cache\nphp artisan route:cache\n
  • Restart the supervisor workers to ensure they also pickup the latest code:
supervisorctl start all\n

Better safe then sorry

Always perform a database backup of your database before doing an update. Always.

You can use mysqldump -uroot -p seat > backup.sql (change root and seat according to your configuration)

"},{"location":"upgrading/from_seat_3_0/bare_metal/","title":"SeAT 3.0 to 4.0 (Bare metal)","text":"

The upgrade path from SeAT 3.0 to SeAT 4.0 requires some manual work. This is primarily due to large amounts of refactoring that made it into SeAT 4.

Info

Major changes have been made to the way packages workg together, especially the eveapi, web and services packages.

The way jobs are queued and queues themselves have also changed, mostly to reduce resource usage and to improve fluency.

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 4. If you are unsure, join us on Slack so that we can tru and assist or redirect you to proper person.

Warning

Before you do anything, read and understand this entire upgrade guide.

Those instructions are valid for bare metal deployment only (non-docker installation). Please refer to docker instructions for a Docker installation.

Remember to do a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

"},{"location":"upgrading/from_seat_3_0/bare_metal/#requirements","title":"Requirements","text":"
  • Check SeAT 4.0 requirements
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
  • Enough storage space to have SeAT 3, SeAT 4 and a backup of your SeAT 3 database.
  • Ensure all your SeAT 3 packages are up-to-date (check this in Settings > SeAT Settings)
"},{"location":"upgrading/from_seat_3_0/bare_metal/#upgrade-procedure","title":"Upgrade Procedure","text":""},{"location":"upgrading/from_seat_3_0/bare_metal/#preparation","title":"Preparation","text":"

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely) - or cause crash during database conversion. Please start to turning SeAT in maintenance mode, cutting jobs and clearing caches before starting the upgrade.

Turn workers down, use the command

service supervisor stop\n

Put SeAT in maintenance mode

sudo -H -u www-data bash -c 'php /var/www/seat/artisan down'\n

Clear cache

sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:cache:clear'\n
"},{"location":"upgrading/from_seat_3_0/bare_metal/#backups","title":"Backups","text":"
  • Make a backup of your SeAT database and store it somewhere safe! Do no skip this step!
  • In your SeAT directory, make a copy of the .env file. This file contains all your SeAT configuration, including tokens watermark required to update your registered users content. These values might be useful in case of failure.
"},{"location":"upgrading/from_seat_3_0/bare_metal/#installing-seat-40","title":"Installing SeAT 4.0","text":"

Rename the current SeAT directory from /var/www/seat to /var/www/seat3. You don't have to update any config since we will only use the command line for the process.

mv /var/www/seat /var/www/seat3\n
"},{"location":"upgrading/from_seat_3_0/bare_metal/#php","title":"PHP","text":"

If it's not already the case, you'll have to deploy at least PHP 7.3 on the server. The provided command bellow will help you in this task and add newly required PHP extensions in the meantime.

apt-get update\napt-get install libpng-dev libfreetype6-dev libjpeg-dev\napt-get install curl openssl zip php7.3-bz2 php7.3-cli php7.3-curl php7.3-dom php7.3-gd php7.3-gmp php7.3-intl php7.3-mbstring php7.3-mysql php7.3-opcache php7.3-redis php7.3-zip\n

Remember to update your NGinX configuration to use the new CGI version. To do so, open configuration file located at /etc/nginx/sites-available/seat and replace

       fastcgi_pass unix:/run/php/php7.1-fpm.sock;\n

with

       fastcgi_pass unix:/run/php/php7.3-fpm.sock;\n
"},{"location":"upgrading/from_seat_3_0/bare_metal/#seat","title":"SeAT","text":"

Once packages have been updated, we will deploy the new SeAT's version using composer.

composer create-project eveseat/seat /var/www/seat \"4.0.*\" --no-dev --no-interaction\n

Once the download is done, you should have seen output such as:

Writing lock file\nGenerating optimized autoload files\n> Illuminate\\Foundation\\ComposerScripts::postAutoloadDump\n> @php artisan package:discover\nDiscovered Package: darkaonline/l5-swagger\nDiscovered Package: eveseat/api\nDiscovered Package: eveseat/console\nDiscovered Package: eveseat/eveapi\nDiscovered Package: eveseat/notifications\nDiscovered Package: eveseat/services\nDiscovered Package: eveseat/web\nPackage manifest generated successfully.\n> @php artisan key:generate\nApplication key [base64:CmhqYNkaIcHo8nYC8LiEWa3U5/+BiTLih5dZftxlV2k=] set successfully.\n

Finally, fix directories permissions using the two commands bellow:

chown -R www-data:www-data /var/www/seat\nchmod -R guo+w /var/www/seat/storage/\n
"},{"location":"upgrading/from_seat_3_0/bare_metal/#setup","title":"Setup","text":"

Now sources have been deployed, we have to update .env configuration file. Use information from backup located at /var/www/seat3/.env to update the newly generated file located at /var/www/seat/.env.

Info

In case you had third party packages installed, it's time to deploy them back. We invite you to report to their own documentation regarding any specific guideline.

Warning

Please pay special attention to APP_KEY, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, EVE_CLIENT_ID, EVE_CLIENT_SECRET and EVE_CALLBACK_URL parameters.

"},{"location":"upgrading/from_seat_3_0/bare_metal/#database","title":"Database","text":"

We will convert database to work with new SeAT version. To do so, we're using common commands disclosed bellow:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'\nsudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'\nsudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\\\Console\\\\database\\\\seeds\\\\ScheduleSeeder'\nsudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde --force'\n
"},{"location":"upgrading/from_seat_3_0/bare_metal/#complete","title":"Complete","text":"

Finally, restore workers states and put SeAT online using initial commands in reverse order.

Put SeAT online

sudo -H -u www-data bash -c 'php /var/www/seat/artisan up'\n

Convert user tokens format from previous version

sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:token:upgrade'\n

Turn workers up

service supervisor start\n
"},{"location":"upgrading/from_seat_3_0/bare_metal/#access","title":"Access","text":"

SeAT 4.0 is coming with a complete revamp of permissions system. As a result, your previous roles haven't been converted. However, they've been keep - so you can configure them with the new system.

You will have to use built-in admin account for your first connexion.

Info

Super administrator is now an user flag and have to be defined at user level instead of Access Permissions. You'll get more information regarding the new system on Admin Login and Authorizations pages.

"},{"location":"upgrading/from_seat_3_0/docker/","title":"SeAT 3.0 to 4.0 (Docker)","text":"

The upgrade path from SeAT 3.0 to SeAT 4.0 requires some manual work. This is primarily due to large amounts of refactoring that made it into SeAT 4.

Info

Major changes have been made to the way packages workg together, especially the eveapi, web and services packages.

The way jobs are queued and queues themselves have also changed, mostly to reduce resource usage and to improve fluency.

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 4. If you are unsure, join us on Slack so that we can tru and assist or redirect you to proper person.

Warning

Before you do anything, read and understand this entire upgrade guide.

Those instructions are valid for Docker deployment only. Please refer to bare metal instructions for a non-docker installation.

Remember to do make a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

"},{"location":"upgrading/from_seat_3_0/docker/#requirements","title":"Requirements","text":"
  • Check SeAT 4.0 requirements
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
  • Enough storage space to have SeAT 3, SeAT 4 and a backup of your SeAT 3 database.
  • Ensure all your SeAT 3 packages are up-to-date (check this in Settings > SeAT Settings)
"},{"location":"upgrading/from_seat_3_0/docker/#docker-upgrade-procedure","title":"Docker Upgrade Procedure","text":"

If you are currently using a docker installation for SeAT 3, you are in for a treat because upgrading is super easy. All we are going to do is bring the v4 stack up, connect your database and watch as the Docker entrypoint takes care of the rest.

This guide is going to step through some quick preparation steps, then perform the upgrade and finally, check that everything worked out as expected. Let's dive in.

"},{"location":"upgrading/from_seat_3_0/docker/#tldr-upgrades","title":"tl;dr upgrades","text":"

We highly reccomend that you read the details of this upgrade guide to get familiar with what has changed. But, if this is your nth upgrade, maybe you just want to get the summary of everything, so here it is:

  • Make a backup of your database.
  • cd to your install dir (which is probably /opt/seat-docker) and bring the stack down with docker-compose down
  • Make a copy of your .env and docker-compose.yml files.
  • Download the new docker-compose.yml file with curl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -o docker-compose.yml.
  • Down the new .env file with curl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -o .env.
  • Upgrade your docker-compose installation. It should be version 1.26 and up.
  • Configure the new .env file. Important configs include the TRAEFIK_ variables, the SEAT_SUBDOMAIN variable. Copy over existing values from your old .env file for the EVE_CLIENT_ variables, the APP_KEY varaible and finally the DB_ variables.
  • Bring the stack back up with docker-compose up -d and watch the migration process.
  • Finally, once the migration process is complete, update the EVE SDE to populate the tables with static data with: docker-compose exec seat-web php artisan eve:update:sde --force -n

\ud83c\udf89

"},{"location":"upgrading/from_seat_3_0/docker/#docker-changes-since-seat-3","title":"Docker changes since SeAT 3","text":"

A number of changes have been made how the docker-compose stack is glued together.

First, the docker repository for SeAT 4 has a new home here, and a new image here.

In SeAT 3, services such as web, workers and cron were all using seperate images. For SeAT 4, we have consilidated all of that into a single image, with a service-aware entrypoint. The code for all of this lives in a new dedicated repository instead of being \"hidden\" away in the script repo here. All of these changes also mean that we now have the ability to properly tag the docker images instead of relying on the latest tag like we did in SeAT 3. Finally.

Next, the default nginx web server has been replaced with Traefik. For the majority of users this means little to no change to what you were used to. However, if you were fronting your instance with another reverse proxy, it is important to be aware of this change. The base image used for the SeAT docker image uses apache2 to serve the web UI, and Traefik reverse proxies to this, exposing it to the world. Advanced users can rip this out, expose the apache server directly and continue using the setup you have. The options are limitless.

"},{"location":"upgrading/from_seat_3_0/docker/#preperation","title":"Preperation","text":"

Before you upgrade, you need to backup.

"},{"location":"upgrading/from_seat_3_0/docker/#backup-your-database","title":"Backup your database","text":"

The single most important thing you need is a backup of your SeAT 3 database. Without a backup you will not be able to recover in case of a disaster. So, head on over to the docker db backup section and do that right now.

"},{"location":"upgrading/from_seat_3_0/docker/#backup-your-env-file","title":"Backup your env file","text":"

The .env file is the one that has your SeAT installations' configuration. It contains things like your SSO Client ID and Secret (aka: credentials). By default, SeAT docker installations live in /opt/seat-docker meaning your .env file will be at /opt/seat-docker/.env. Make a copy of this file and store it somewhere safe.

"},{"location":"upgrading/from_seat_3_0/docker/#upgrade-docker-compose","title":"Upgrade docker-compose","text":"

The docker-compose binary should be upgraded so that we can make use of ${VARIABLES} inside .env files.

If you installed docker-compose using your OS' package manager, upgrade the tool using that. Otherwise, a curl invocation to download the latest version should also work.

curl -L https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose\nchmod +x /usr/local/bin/docker-compose\n
"},{"location":"upgrading/from_seat_3_0/docker/#stop-seat-3","title":"Stop SeAT 3","text":"

First, we need to stop the SeAT 3 stack. Assuming you have the default /opt/seat-docker location for your installation, cd to it first and then run:

docker-compose down\n

The output should be similar to this:

root@seat:/opt/seat-docker# docker-compose down\nStopping seat-nginx   ... done\nStopping seat-cron    ... done\nStopping seat-worker  ... done\nStopping seat-app     ... done\nStopping seat-mariadb ... done\nStopping seat-redis   ... done\nRemoving seat-nginx   ... done\nRemoving seat-cron    ... done\nRemoving seat-worker  ... done\nRemoving seat-app     ... done\nRemoving seat-mariadb ... done\nRemoving seat-redis   ... done\nRemoving network seat-docker_seat-network\n
"},{"location":"upgrading/from_seat_3_0/docker/#upgrading-to-seat-4","title":"Upgrading to SeAT 4","text":""},{"location":"upgrading/from_seat_3_0/docker/#get-the-new-docker-compose-file","title":"Get the new docker-compose file","text":"

Warning

If you have made customisations to how you deployed SeAT with docker-compose, then you should probably not be replacing the compose file like we are about to do. Instead, have a look at the new one here and adapt.

Next, we will download the new SeAT 4 docker-compose file. Do that with:

mv docker-compose.yml docker-compose.yml.back\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -o docker-compose.yml\n

With this we have created a copy of the older docker-compose file (just in case), and downloaded the new one.

"},{"location":"upgrading/from_seat_3_0/docker/#get-the-new-env-file","title":"Get the new .env file","text":"

The next step is to get a fresh copy of the new .env file to use together with the new docker-compose setup. There have been a number of changes to this file (primarily as a result of the web server swap out) which we will describe in the next section.

Get it with:

mv .env .env.back\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -o .env\n
"},{"location":"upgrading/from_seat_3_0/docker/#configure-the-new-env-file","title":"Configure the new .env file","text":"

Info

This is admitedly the hardest part of the migtation, so pay close attention. Take it slowly and think about what you are doing here.

There are four main settings categories that need to be updated in the new .env file. Those are:

  • Traefik (webserver)
  • EVE Online SSO Config
  • The application key
  • Database credentials

All of these categories will be described below in detail. For all of them, you have to open the newly downloaded .env file in a text editor and update the values. To be sure you are editing the correct file, check its header. It should say:

# SeAT Docker Compose Configuration\n\n# Web server configuration.\n# SeAT running in a docker-compose setup ships with Traefik\n# as the default web server. You only need to configure the\n# parent domain and port where the web server will listen.\n# In most cases, just configuring the domain will be all\n# you need to do.\n
"},{"location":"upgrading/from_seat_3_0/docker/#traefik","title":"Traefik","text":"

As mentioned earlier. The web server has been swapped out in favour of Traefik. As a result, you need to set a few configuration options to get the web UI to work. If you have a setup where you have configured something like nginx outside of your Docker installation, we highly reccomend you just remove that and switch over to Traefik. Of anything, it's handling of TLS with Let's Encrypt is quite literally a one-time setup and forget thing.

Inside the .env file, Traefik specific configuration options are prefixed with TRAEFIK_. They are:

TRAEFIK_DOMAIN=seat.local\nTRAEFIK_HTTPS_PORT=443\nTRAEFIK_HTTP_PORT=80\nTRAEFIK_ACME_EMAIL=you@domain.com\n

These fields need to be updated as follows:

  • TRAEFIK_DOMAIN: This is the base domain where your SeAT installation lives. For example, if your SeAT 3 installation lives at seat.domain.com, you enter domain.com here.
  • TRAEFIK_HTTPS_PORT: This is the external port that will be open to the world. SeAT 4 in docker with Traefik will only listen on TLS as well. Since its configured to be 443, it will most likely clash with your external web server. We reccomend that you just disable your external web server and use Traefik. TLS configuration with it is a breeze!
  • TRAEFIK_HTTPS_PORT: This is the non-TLS port that Let's Encrypt (as part of the ACME protocol) will connect to during certificate renewals. SeAT will not be available here.
  • TRAEFIK_ACME_EMAIL: The email address used for Let's Encrypt certificate renewals.

A SEAT_SUBDOMAIN value is also present, which sets the subdomain where the SeAT web UI lives. This value needs to match what your SeAT 3 installation used, especially so that the existing SSO application you have configured on the EVE SSO portal matches the configured callback url.

By default, most folks will only configure the domain, subdomain and email and be done. Of course, if you have custom configurations and needs, feel free to adapt.

"},{"location":"upgrading/from_seat_3_0/docker/#traefik-tls","title":"Traefik - TLS","text":"

Traefik should handle all of the relevant configuration to get your site to listen with a valid TLS certificate. The secrets for the TLS configuration in Traefik relies on an acme.json file which you should mount into the Traefik container from the outside so that it persists restart.

Prepare the json file from within /opt/seat-docker with:

mkdir acme\ntouch acme/acme.json\nchmod 600 acme/acme.json\n

Next, make sure you have the TRAEFIK_ACME_EMAIL variable set, and finally, uncomment the labels that will make use of the Let's Encrypt cert resolver in the docker-compose.yml file. By default, they will look like this, whereby you need to remove the # in front.

(Note: the line below in docker-compose.yml is located in two places, only remove the # from seat-web)

#- \"traefik.http.routers.seat-web.tls.certResolver=primary\"\n
"},{"location":"upgrading/from_seat_3_0/docker/#eve-online-sso","title":"EVE Online SSO","text":"

Since SeAT's authentication relies on EVE's SSO, you need to configure the relevant client id and secret. You can find your old values in the backup you have made of the .env file. The values you need to set are:

  • EVE_CLIENT_ID
  • EVE_CLIENT_SECRET

For the callback URL, ensure that you have correctly configured the SEAT_SUBDOMAIN value in the previous step.

"},{"location":"upgrading/from_seat_3_0/docker/#the-seat-application-key","title":"The SeAT Application Key","text":"

By default, the APP_KEY value for a fresh .env file will be insecure. This is a purposefully incorrectly formatted value. You can simply set this to the value you have for the same variable in your backup .env file.

"},{"location":"upgrading/from_seat_3_0/docker/#database-details","title":"Database details","text":"

This is one of the more important steps. The database configuration needs to match what your SeAT 3 installation used because the database data lives in a docker volume. When the stack will start up for the first time again, the SeAT 4 container will have access to the SeAT 3 database volume, and run migrations there. So, you need to copy the database credentials from the old .env file to the new one.

The variable names have remained unchanged, but for referece they are:

DB_DATABASE=seat\nDB_USERNAME=seat\nDB_HOST=mariadb\nDB_PASSWORD=i_should_be_changed\n
"},{"location":"upgrading/from_seat_3_0/docker/#bringing-seat-4-up","title":"Bringing SeAT 4 up","text":"

The only thing that is left to do is to start the stack up again. The first time we are goin to start SeAT 4 we wont use the -d flag. This is just so that you can see what's happening during the upgrade procedure. So, start SeAT with:

docker-compose up\n

You should see something like this happen when you run the above command:

root@seat:/opt/seat-docker# docker-compose up\nCreating network \"seat-docker_seat-network\" with the default driver\nPulling mariadb (mariadb:10)...\n10: Pulling from library/mariadb\n3ff22d22a855: Already exists\ne7cb79d19722: Already exists\n323d0d660b6a: Already exists\n\n...\n

After a while, migrations should start running:

...\n\nseat-web_1     | starting web service\nseat-web_1     | Starting first run routines\nseat-web_1     | Migrating: 2018_06_05_110000_drop_assets_from_outposts\nseat-web_1     | Migrated:  2018_06_05_110000_drop_assets_from_outposts (0.02 seconds)\nseat-web_1     | Migrating: 2019_02_09_110731_drop_type_from_notification_groups\nseat-web_1     | Migrated:  2019_02_09_110731_drop_type_from_notification_groups (0.01 seconds)\nseat-web_1     | Migrating: 2019_05_11_164831_add_permission_role_filter\n\n...\n

Warning

Do not interrupt the database migration phase. It will leave your database in a potentially corrupt state, meaning you are going to have to do some extra pluming to get a backup restored. Not a train smash, but not worth it.

Be patient, there are many, many database changes that need to apply.

Eventually, when everything is done you should start seeing the following output:

seat-worker_1  | [2020-08-19 21:11:45][2] Processing: Seat\\Eveapi\\Jobs\\Status\\Status\nseat-worker_1  | [2020-08-19 21:11:45][1] Processing: Seat\\Eveapi\\Jobs\\Status\\Esi\nseat-worker_1  | [2020-08-19 21:11:46][2] Processed:  Seat\\Eveapi\\Jobs\\Status\\Status\nseat-worker_1  | [2020-08-19 21:11:46][1] Processed:  Seat\\Eveapi\\Jobs\\Status\\Esi\n

This is a good sign, and means everything is now ready!

"},{"location":"upgrading/from_seat_3_0/docker/#check-your-installation","title":"Check your installation","text":"

The first obvious step will be to check that you can access the web UI. If not, something is probably weird with the web server configuration and needs some tweaking.

If everything seems to be working fine, you can hit crtl + c which will bring the stack down gracefully.

^CGracefully stopping... (press Ctrl+C again to force)\nStopping seat-docker_seat-cron_1   ...\nStopping seat-docker_seat-worker_1 ...\nStopping seat-docker_seat-web_1    ...\nStopping seat-docker_traefik_1     ... done\nStopping seat-docker_redis_1       ...\n

Then, bring it back up with the -d flag.

docker-compose up -d\n
"},{"location":"upgrading/from_seat_3_0/docker/#convert-user-tokens","title":"Convert User Tokens","text":"

SeAT 4.x is using the new CCP Token format (v2). In order to use registered tokens from your previous installation, you'll have to run the following command:

docker-compose exec seat-web php artisan seat:token:upgrade\n
"},{"location":"upgrading/from_seat_3_0/docker/#update-eve-sde","title":"Update EVE SDE","text":"

This is the final step, for real. You need to update the EVE SDE. With your stack up and running (after executing docker-compose up -d), you can now force an SDE update with:

docker-compose exec seat-web php artisan eve:update:sde --force -n\n

Congrats, and welcome to SeAT 4!

Info

Super administrator is now an user flag and have to be defined at user level instead of Access Permissions. You'll get more information regarding the new system on Admin Login and Authorizations pages.

"},{"location":"upgrading/from_seat_4_0/bare_metal/","title":"SeAT 4.x to 5.0 (Bare metal)","text":"

The upgrade path from SeAT 4.0 to SeAT 5.0 requires a tiny amount of manual work.

Warning

Before you do anything, read and understand this entire upgrade guide.

Those instructions are valid for bare metal deployment only (non-docker installation). Please refer to docker instructions for a Docker installation.

Remember to do a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

Info

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 5. If you are unsure, join us on Discord so that we can assist or redirect you to the proper person.

"},{"location":"upgrading/from_seat_4_0/bare_metal/#requirements","title":"Requirements","text":"
  • Check [SeAT 5.0 requirements]
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
  • Enough storage space to have SeAT 5, SeAT 4 and a backup of your SeAT 4 database.
  • Ensure all your SeAT 4 packages are up-to-date (check this in Settings > SeAT Settings)
"},{"location":"upgrading/from_seat_4_0/bare_metal/#upgrade-procedure","title":"Upgrade Procedure","text":""},{"location":"upgrading/from_seat_4_0/bare_metal/#preparation","title":"Preparation","text":"

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely) - or cause crash during database conversion. Please start to turning SeAT in maintenance mode, cutting jobs and clearing caches before starting the upgrade.

Turn workers down, use the command

systemctl stop supervisor.service\n

Put SeAT in maintenance mode

sudo -H -u www-data bash -c 'php /var/www/seat/artisan down'\n

Clear cache

sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:cache:clear'\n
"},{"location":"upgrading/from_seat_4_0/bare_metal/#backups","title":"Backups","text":"
  • Make a backup of your SeAT database and store it somewhere safe! Do no skip this step!
  • In your SeAT directory, make a copy of the .env file. This file contains all your SeAT configuration, including the keys to the ESI tokens required to update your registered users content. These values might be useful in case of failure.
"},{"location":"upgrading/from_seat_4_0/bare_metal/#installing-seat-50","title":"Installing SeAT 5.0","text":"

Rename the current SeAT directory from /var/www/seat to /var/www/seat4. You don't have to update any config since we will only use the command line for the process.

mv /var/www/seat /var/www/seat4\n
"},{"location":"upgrading/from_seat_4_0/bare_metal/#php","title":"PHP","text":"

SeAT 5 needs PHP 8.2 on the server. The provided command bellow will help you in this task and add newly required PHP extensions in the meantime.

apt-get update\napt-get install libpng-dev libfreetype6-dev libjpeg-dev\napt-get install openssl zip php8.2-fpm php8.2-bz2 php8.2-cli php8.2-curl php8.2-dom php8.2-gd php8.2-gmp php8.2-intl php8.2-mbstring php8.2-mysql php8.2-opcache php8.2-redis php8.2-zip\n

Remember to update your NGinX configuration to use the new CGI version. To do so, open configuration file located at /etc/nginx/sites-available/seat and replace

fastcgi_pass unix:/run/php/php7.3-fpm.sock;\n

with

fastcgi_pass unix:/run/php/php8.2-fpm.sock;\n

Restart nginx to load the changes:

systemctl restart nginx.service\n
"},{"location":"upgrading/from_seat_4_0/bare_metal/#seat","title":"SeAT","text":"

Once packages have been updated, we will deploy the new SeAT's version using composer.

composer create-project eveseat/seat /var/www/seat \"5.0\" --no-dev --no-interaction\n

Once the download is done, you should have seen output such as:

76 packages you are using are looking for funding.\nUse the `composer fund` command to find out more!\n> @php artisan vendor:publish --tag=laravel-assets --ansi --force\n\nINFO  Publishing [laravel-assets] assets.  Copying directory [vendor/laravel/horizon/public] to [public/vendor/horizon]  DONE\n  Copying directory [vendor/opcodesio/log-viewer/public] to [public/vendor/log-viewer]  DONE\n\nNo security vulnerability advisories found.\n> @php artisan key:generate --ansi\n\nINFO  Application key set successfully.

Finally, fix directories permissions using the two commands bellow:

chown -R www-data:www-data /var/www/seat\nchmod -R guo+w /var/www/seat/storage/\n
"},{"location":"upgrading/from_seat_4_0/bare_metal/#setup","title":"Setup","text":"

Now sources have been deployed, we have to update .env configuration file. Use information from backup located at /var/www/seat4/.env to update the newly generated file located at/var/www/seat/.env.

Info

In case you had third party packages installed, it's time to deploy them back. We invite you to report to their own documentation regarding any specific guideline.

Warning

Please pay special attention to APP_KEY, APP_URL, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, EVE_CLIENT_ID, EVE_CLIENT_SECRET and EVE_CALLBACK_URL parameters.

"},{"location":"upgrading/from_seat_4_0/bare_metal/#database","title":"Database","text":"

We will convert database to work with new SeAT version. To do so, we're using common commands disclosed bellow:

sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'\nsudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'\nsudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\\\Services\\\\Database\\\\Seeders\\\\PluginDatabaseSeeder'\nsudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde --force'\n
"},{"location":"upgrading/from_seat_4_0/bare_metal/#complete","title":"Complete","text":"

Finally, restore workers states and put SeAT online using initial commands in reverse order.

Put SeAT online

sudo -H -u www-data bash -c 'php /var/www/seat/artisan up'\n

Turn workers up

systemctl start supervisor.service\n
"},{"location":"upgrading/from_seat_4_0/docker/","title":"SeAT 4.x to 5.0 (Docker)","text":"

The upgrade path from SeAT 4.0 to SeAT 5.0 requires a tiny amount of manual work.

Info

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 5. A compatibility table can be found on the Community Packages page. If you are unsure, join us on Discord so that we can tru and assist or redirect you to proper person.

Users of recursivetree/seat-info need to follow separate instructions after the migrating the core to seat 5.

Warning

Before you do anything, read and understand this entire upgrade guide.

Those instructions are valid for Docker deployment only. Please refer to bare metal instructions for a non-docker installation.

Remember to do make a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

"},{"location":"upgrading/from_seat_4_0/docker/#requirements","title":"Requirements","text":"
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
  • Enough storage space to have SeAT 4, SeAT 5 and a backup of your SeAT 4 database.
  • Ensure all your SeAT 4 packages are up-to-date (check this in Settings > SeAT Settings)
"},{"location":"upgrading/from_seat_4_0/docker/#docker-upgrade-procedure","title":"Docker Upgrade Procedure","text":"

If you are currently using a docker installation for SeAT 4, upgrading is easy as never before. You need to make a few changes to your docker stack configuration, restart the stack, and you're good to go.

This guide is going to step through some quick preparation steps, then perform the upgrade and finally, check that everything worked out as expected. Let's dive in.

"},{"location":"upgrading/from_seat_4_0/docker/#tldr-upgrades","title":"tl;dr upgrades","text":"

We highly recommend that you read the details of this upgrade guide to get familiar with what has changed. But, if this is your nth upgrade, maybe you just want to get the summary of everything, so here it is:

  • Make a backup of your database.
  • cd to your install dir (which is probably /opt/seat-docker) and bring the stack down with 
    docker compose down\n
  • Make a copy of your .env file using 
    cp .env .env.seat4.bak\n
  • Make a copy of your current compose file using 
    cp docker-compose.yml docker-compose.yml.seat4.bak\n
  • Download the new docker-compose.yml file with 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.yml -o docker-compose.yml`\n
  • Download the new database override docker-compose.mariadb.yml file with 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.mariadb.yml -o docker-compose.mariadb.yml\n
  • Download the new traefik override docker-compose.traefik.yml file with 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.traefik.yml -o docker-compose.traefik.yml\n
  • Download the new proxy override docker-compose.proxy.yml file with 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.proxy.yml -o docker-compose.proxy.yml\n
  • Download the new .env file template using 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/.env -o .env\n
  • Update the new .env file using your backup .env.seat4.bak

The table bellow is provided as a variable mapping between SeAT 4.x and SeAT 5.x. You can use it as a reference.

SeAT 4.x SeAT 5.x TRAEFIK_DOMAIN=seat.local SEAT_DOMAIN=seat.seat.local SEAT_SUBDOMAIN=seat SEAT_DOMAIN=seat.seat.local REDIS_HOST=redis REDIS_HOST=cache PROXY_BACKEND_HTTP_PORT=8080 LOG_LEVEL=error

Info

With SeAT 5.x, there is non longer default database and proxy. You can mix services are your needs. However, we continue to provide a few default layout usable out of the box as an option.

Using TraefikUsing reverse proxy

In case you want to use Traefik front of SeAT ui container, you'll need to setup the following environment variable: TRAEFIK_ACME_EMAIL. You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up

In case you want to use a custom reverse proxy front of SeAT ui container, you'll need to setup the new environment variable PROXY_BACKEND_HTTP_PORT. You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up

Since we didn't startup the stack using daemon mode - the overall migration and process is run at front. This will allow you to detect any issue without having a container running in panic mode. When SeAT will be ready to serve your requests and have successfully been upgrade, you'll see the following output :

2023-06-02 09:49:33          ****////////////                                                   \n2023-06-02 09:49:33      ***                 ///                                                   \n2023-06-02 09:49:33   ***                      //                                                 \n2023-06-02 09:49:33   **     **  //   ///        //                                                \n2023-06-02 09:49:33  **      ***  ///             //      ////////@@@@@@@@@@@@@@@(/////@@@//////////\n2023-06-02 09:49:33            **/   ///   /////////     *///&@@@@@@@&/////#@@@@%//%///#@@@@@(///@ \n2023-06-02 09:49:33  **     *** //////// /                @///////@@///@@@///@@@///@@///@@@@@(///@ \n2023-06-02 09:49:33  **      ***   ///   //       //      @@@@@////@/////////@@//////////@@@@(///@ \n2023-06-02 09:49:33   **         ///  //   /     //      *////////@@@///////@@///@@@@@@///@@@(///@ \n2023-06-02 09:49:33    ***         //// ///    ///                                              \n2023-06-02 09:49:33       ***                ///                                              \n2023-06-02 09:49:33          ****////////////\n2023-06-02 09:49:33 \n2023-06-02 09:49:33 \n2023-06-02 09:49:33 SeAT is now ready to serve requests\n2023-06-02 09:49:33 \n2023-06-02 09:49:33 Open your browser and go to 'https://seat.domain.tld'\n2023-06-02 09:49:33 Run 'docker compose exec front php artisan seat:admin:login' to get a temporary link in order to sign-in as built-in admin user account (or use bellow one)\n2023-06-02 09:49:33 \n2023-06-02 09:49:33 SeAT Admin Login URL Generator\n2023-06-02 09:49:33 Checking if 'admin' is a super user\n2023-06-02 09:49:33 Generating authentication token\n2023-06-02 09:49:33 \n2023-06-02 09:49:33 Your authentication URL is valid for 60 seconds.\n2023-06-02 09:49:33 https://seat.domain.tld/auth/login/admin/aDvMAcd7GQPXFfhS3aIH9dh4opwcvASB\n2023-06-02 09:49:33 \n2023-06-02 09:49:33 \n2023-06-02 09:49:33 AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.19.0.4. Set the 'ServerName' directive globally to suppress this message\n2023-06-02 09:49:33 AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.19.0.4. Set the 'ServerName' directive globally to suppress this message\n2023-06-02 09:49:33 [Fri Jun 02 07:49:33.524019 2023] [mpm_prefork:notice] [pid 1] AH00163: Apache/2.4.56 (Debian) PHP/8.2.6 configured -- resuming normal operations\n2023-06-02 09:49:33 [Fri Jun 02 07:49:33.524084 2023] [core:notice] [pid 1] AH00094: Command line: 'apache2 -D FOREGROUND'\n

Try to authenticate yourself and verify everything is working well. If you don't find any issue, you can now restart the stack in daemon mode \ud83c\udf89.

Use Ctrl+C in order to kill the stack and restart it in background:

Using TraefikUsing reverse proxy 
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up\n
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up\n
"},{"location":"upgrading/from_seat_4_0/docker/#docker-changes-since-seat-4","title":"Docker changes since SeAT 4","text":"

There have been a few minor changes to the docker-compose.yml file. Most notably, the containers have been renamed to disclose their purpose easier, we have moved from Dockerhub to GitHub Container Registry, and the stack now has a persistent storage volume.

If you customized your docker stack deployment, it is recommended that you take a look at the new docker-compose.yml file yourselves to see what exactly changed. Last but not least, try to avoid tuning standard files as must as possible and use override syntax instead with a docker-compose.override.yml file (see official documentation).

"},{"location":"upgrading/from_seat_4_0/docker/#preperation","title":"Preperation","text":"

Before you upgrade, you need to backup.

"},{"location":"upgrading/from_seat_4_0/docker/#backup-your-database","title":"Backup your database","text":"

The single most important thing you need is a backup of your SeAT 4 database. Without a backup you will not be able to recover in case of a disaster. So, head on over to the docker db backup section and do that right now.

"},{"location":"upgrading/from_seat_4_0/docker/#backup-your-env-file","title":"Backup your env file","text":"

The .env file is the one that has your SeAT installations' configuration. It contains things like your SSO Client ID and Secret (aka: credentials). By default, SeAT docker installations live in /opt/seat-docker meaning your .env file will be at /opt/seat-docker/.env. Make a copy of this file and store it somewhere safe.

"},{"location":"upgrading/from_seat_4_0/docker/#stop-seat-4","title":"Stop SeAT 4","text":"

First, we need to stop the SeAT 4 stack. Assuming you have the default /opt/seat-docker location for your installation, cd to it first and then run:

docker compose down\n

The output should be similar to this:

root@seat:/opt/seat-docker# docker compose down\nStopping seat-web   ... done\nStopping seat-cron    ... done\nStopping seat-worker  ... done\nRemoving seat-traefik     ... done\nStopping seat-mariadb ... done\nStopping seat-redis   ... done\nRemoving seat-web   ... done\nRemoving seat-cron    ... done\nRemoving seat-worker  ... done\nRemoving seat-traefik     ... done\nRemoving seat-mariadb ... done\nRemoving seat-redis   ... done\nRemoving network seat-docker_seat-network\n
"},{"location":"upgrading/from_seat_4_0/docker/#upgrading-to-seat-5","title":"Upgrading to SeAT 5","text":""},{"location":"upgrading/from_seat_4_0/docker/#get-the-new-docker-compose-files","title":"Get the new docker-compose files","text":"

Warning

If you have made customisations to how you deployed SeAT with docker-compose, then you should probably not

be replacing the compose file like we are about to do. Instead, have a look at the new one here and adapt.

Next, we will download the new SeAT 5 docker-compose files. Do that with:

mv docker-compose.yml docker-compose.yml.seat4.bak\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.yml -o docker-compose.yml\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.mariadb.yml -o docker-compose.mariadb.yml\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.traefik.yml -o docker-compose.traefik.yml\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.proxy.yml -o docker-compose.proxy.yml\n

With this we have created a copy of the older docker-compose file (just in case), and downloaded the new one.

"},{"location":"upgrading/from_seat_4_0/docker/#update-the-env-file","title":"Update the .env file","text":"

This is one of the more important steps. The database configuration needs to be updated.

The easier is probably to download the new template and adapt variables according to your previous configuration as some of them have been removed, newest appeared and overall have been reordered.

mv .env .env.seat4.bak\ncurl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/.env -o .env\n

You can refer at any time to the online version of .env file on GitHub The table bellow is provided as a variable mapping between SeAT 4.x and SeAT 5.x. You can use it as a reference.

SeAT 4.x SeAT 5.x TRAEFIK_DOMAIN=seat.local SEAT_DOMAIN=seat.seat.local SEAT_SUBDOMAIN=seat SEAT_DOMAIN=seat.seat.local REDIS_HOST=redis REDIS_HOST=cache PROXY_BACKEND_HTTP_PORT=8080 LOG_LEVEL=error"},{"location":"upgrading/from_seat_4_0/docker/#bringing-seat-5-up","title":"Bringing SeAT 5 up","text":"

The only thing that is left to do is to start the stack up again. The first time we are going to start SeAT 5 we won't use the -d flag. This is just so that you can see what's happening during the upgrade procedure. So, start SeAT with:

Using TraefikUsing reverse proxy

In case you want to use Traefik front of SeAT ui container, you'll need to setup the following environment variable: TRAEFIK_ACME_EMAIL. You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up

In case you want to use a custom reverse proxy front of SeAT ui container, you'll need to setup the new environment variable PROXY_BACKEND_HTTP_PORT. You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up

You should first see some download progress bars downloading the new SeAT version.

After a while, seat should start up similar to this:

...\n\nseat_local-front-1  | mysqld is alive\nseat_local-front-1  | PONG\nseat_local-front-1  | starting web service\nseat_local-front-1  | Processing plugins from SEAT_PLUGINS\nseat_local-front-1  | Loading composer repositories with package information\nseat_local-front-1  | Info from https://repo.packagist.org: #StandWithUkraine\nseat_local-front-1  | Updating dependencies\n...\n

Warning

Do not interrupt SeAT during this phase. It will leave your database in a potentially corrupt state, meaning you are going to have to do some extra pluming to get a backup restored. Not a train smash, but not worth it.

Eventually, when everything is done you should start seeing the following output:

seat_local-front-1  | AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.25.0.5. Set the 'ServerName' directive globally to suppress this message\nseat_local-front-1  | AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.25.0.5. Set the 'ServerName' directive globally to suppress this message\nseat_local-front-1  | [Sun May 21 21:10:46.869842 2023] [mpm_prefork:notice] [pid 1] AH00163: Apache/2.4.56 (Debian) PHP/8.1.19 configured -- resuming normal operations\nseat_local-front-1  | [Sun May 21 21:10:46.869944 2023] [core:notice] [pid 1] AH00094: Command line: 'apache2 -D FOREGROUND'\n

This is a good sign, and means everything is now ready!

"},{"location":"upgrading/from_seat_4_0/docker/#check-your-installation","title":"Check your installation","text":"

The first obvious step will be to check that you can access the web UI. If not, something is probably weird with the web server configuration and needs some tweaking.

If everything seems to be working fine, you can hit ++crtl+c++ which will bring the stack down gracefully. This might take up to 30 seconds.

^CGracefully stopping... (press Ctrl+C again to force)\nStopping seat-docker_scheduler_1 ...\nStopping seat-docker_worker_1    ...\nStopping seat-docker_front_1     ...\nStopping seat-docker_traefik_1   ... done\nStopping seat-docker_cache_1     ...\n

Then, bring it back up with the -d flag.

Using TraefikUsing reverse proxy

In case you want to use Traefik front of SeAT ui container, you'll need to setup the following environment variable: TRAEFIK_ACME_EMAIL. You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d

In case you want to use a custom reverse proxy front of SeAT ui container, you'll need to setup the new environment variable PROXY_BACKEND_HTTP_PORT. You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d

Congrats, and welcome to SeAT 5!

"},{"location":"upgrading/from_seat_4_0/docker/#problems","title":"Problems","text":"

Should you have any issue with the installation, please contact us on Discord.

"},{"location":"user_guides/moons_reporter/","title":"Moons Reporter","text":""},{"location":"user_guides/moons_reporter/#moons-reporter","title":"Moons Reporter","text":"

Introduced in SeAT 4.0, a new tool is available to assist you in your moon management task by leveraging your intelligence desk. Like your old google/excel sheet, it will gather all your intel related to moon probing. It provides a centralized and convenient way to store reports and search through them.

Of course, like other modules, you are able to restrict its usage using ACL by choosing who can view it and/or import reports.

"},{"location":"user_guides/moons_reporter/#importing-reports","title":"Importing reports","text":"

Seeding an intelligence database is usually a really long task. The Moons Reporter simplifies the process as much as possible by accepting your raw moon report collected by the in-game moon probing interface.

Here is the process which need to be follow in order to be able to import a new moon report :

  • fire your probe in-game and wait for the report to land
  • use the \"Copy to Clipboard\" button from your \"Moon Probe and Analysis\" window
  • go on the Moons Report and hit the \"Import\" button located on top right (1)
  • paste copied content in the opening modal and hit \"Post report\"

That's all, SeAT will take care of your report and apply change accordingly.

Tip

You can paste multiple moon report in once - so, to gain time and save clicks, you will probably prefer to scans all moons in a system before importing them into SeAT.

Info

When importing a report targeting an already imported moon report, existing data will be erased and replaced by the new report.

Caution

In case you have to import data from an existing sheet, you will have to generate report based on your information. Please put an eye into migrate section from this documentation.

"},{"location":"user_guides/moons_reporter/#advanced-search","title":"Advanced Search","text":"

The Moons Reporter is shipped with an advanced search panel (2) which allow you to search moons by different criteria :

  • region
  • constellation
  • system
  • rank
  • produces

Region, Constellation and System filters will be driven together depending on what you're doing - making your search easier.

You are able to provide multiple rank into the rank filter (like ubiquitous, common, uncommon, rare and exceptional). When you are using this filter, only moon which contain all criteria will be displayed. For example, if you are searching for a moon which contain common and uncommon materials, simply select both criteria.

Like rank filter, the produces filter is allowing you to track for moons containing multiple materials. As an example, you can search for moons producing both Vanadium and Cobalt.

To make a search, once you put your criteria, use the search button.

"},{"location":"user_guides/moons_reporter/#moon-information","title":"Moon Information","text":""},{"location":"user_guides/moons_reporter/#moon-metadata","title":"Moon Metadata","text":"

Main pane (3) is showing you the list of all probed moons. You'll get quick intel on them with indicator and sovereignty columns. However, in case you want more information regarding a moon, you can click on the eye button which will show you the moon card.

Displayed sovereignty depends on public in-game collected intel regarding systems. Those data are updated once a day - after down-time.

"},{"location":"user_guides/moons_reporter/#moon-card","title":"Moon Card","text":"

You are able to access details regarding a moon, simple by clicking on the eye button, located in the action column. Moon card will give you some valuable information like contained raw materials, reprocessed materials and reactions candidates.

The Moons Reporter is not only showing you types but also figures like volume, quantity and estimated value. All of them are computed based on a regular chunk of 20,000.00m3 - and upgraded to 30 days for convenience. The base reprocessing yield is 80% - however, you are able to determine which yield must be used into your user profile.

"},{"location":"user_guides/moons_reporter/#moon-stats","title":"Moon Stats","text":"

Some stats are provide in Moons Reporter footer (4). They are showing you the number of raw materials, per rank, from all your scanned moons. Those stats are list in the same order as the indicator column :

  • Gaz or Ubiquitous asteroids
  • R8 or Common asteroids
  • R16 or Uncommon asteroids
  • R32 or Rare asteroids
  • R64 or Exceptional asteroids
  • Ore (standard asteroids - like Scordite, Spodumain, etc...)
"},{"location":"user_guides/moons_reporter/#migrating","title":"Migrating","text":"

Moons Reporter can only accept reports using Eve Online raw format. As a result, you will probably not be able to import data from an existing sheet without process. Luckily, the used format is quite simple to recover from collected data. You will find bellow a sample :

Moon    Moon Product    Quantity    Ore TypeID  SolarSystemID   PlanetID    MoonID\n\nOP9L-F II - Moon 1\n    Glossy Scordite 0.300030559301  46687   30002173    40138526    40138527\n    Immaculate Jaspet   0.328855156898  46682   30002173    40138526    40138527\n    Pellucid Crokite    0.287893354893  46677   30002173    40138526    40138527\n    Sylvite 0.083220936358  45491   30002173    40138526    40138527\n

Keep the two first lines as it, it's the report header. You will then have same format for every moon you need to put inside the report :

  • The full qualified moon name
  • One line per moon compound - indented by a tabulation

Moon compound line are built using :

  • Type name
  • Rate (number between 0 and 1, using . a decimal separator - without thousands separator)
  • Type identifier (number without either decimal or thousands separator)
  • Solar system identifier (number without either decimal or thousands separator)
  • Planet identifier (number without either decimal or thousands separator)
  • Moon identifier (number without either decimal or thousands separator)

If you need either the type name or the type identifier, you can use the amazing work from Fuzzy Steve :

  • Types information
  • Celestial information

Caution

Take care of separators. Report is using tabulations between column and not simple spaces. Also, each line must end with an end line and a carriage return character (CRLF - or Windows carriage return format)

"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 00000000..c0bbd2c4 --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,208 @@ + + + + https://eveseat.github.io/docs/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/community_packages/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/styling/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/troubleshooting/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/about/contact/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/about/reporting_bugs/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/admin_login/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/authorizations/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/buckets/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/docker_admin/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/scaled_deployments/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/squads/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/admin_guides/understanding_tracking/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/configuration_overload/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/env_file_reference/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/esi_configuration/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/eve_administrative_contact/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/sde_overload/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/email_setup/gmail/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/configuration/email_setup/mailgun/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/core_package_breakdown/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/developer_installation/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/development_tips/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/job_queue_flow/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/notifications_implementation/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/package_development/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/seat_api/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/developer_guides/updating_plugins/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/installation/docker_installation/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/installation/manual_installation/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/installation/requirements/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/installation/old_versions/docker_installation_seat_4/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/installation/old_versions/manual_installation_seat_4/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/from_seat_1_0/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/from_seat_2_0/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/general/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/from_seat_3_0/bare_metal/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/from_seat_3_0/docker/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/from_seat_4_0/bare_metal/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/upgrading/from_seat_4_0/docker/ + 2024-02-04 + daily + + + https://eveseat.github.io/docs/user_guides/moons_reporter/ + 2024-02-04 + daily + + \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz new file mode 100644 index 00000000..da781f94 Binary files /dev/null and b/sitemap.xml.gz differ diff --git a/styling/index.html b/styling/index.html new file mode 100644 index 00000000..65cf0be9 --- /dev/null +++ b/styling/index.html @@ -0,0 +1,1503 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Styling - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Styling

+

By default, SeAT uses Bootstrap 3 and the Admin LTE template.

+

You may want to customise SeAT design to match either your corporation or alliance colours.

+

To do so, you can use two available css hooks :

+
    +
  • custom-layout-mini.css used by the sign-in page
    • +
  • custom-layout.css used by all the entier application, globally
    • +
+

Bare Metal Installs

+

Both files must be located into your public directory.

+
+

Example

+

Using the default base directory, you'll get the following path : +- /var/www/seat/public/custom-layout-mini.css +- /var/www/seat/public/custom-layout.css

+
+

These files are loaded automatically if they are detected - you have nothing else to do to enable them.

+

Docker Installs

+

An example of adding these to your Web UI container is provided below:

+
+

Note

+

Do note the version in docker-compose.yml and reflect this in your override file otherwise version mismatches will occur.

+
+
    +
  • Creating custom directory in /opt/seat-docker/ and add files to new directory
    • +
  • Creating docker-compose.override.yml in /opt/seat-docker/ directory
    • +
  • Adding following code to docker-compose.override.yml Note: Uncomment the needed file(s) by removing the #
    • +
+
+
+
+
1
+2
+3
+4
+5
+6
+7
+8
version: "3.2"
+
+services:
+
+  seat-web:
+    volumes:
+#      - /opt/seat-docker/custom/custom-layout-mini.css:/var/www/seat/public/custom-layout-mini.css
+#      - /opt/seat-docker/custom/custom-layout.css:/var/www/seat/public/custom-layout.css
+
+

Once you have placed the files you will need to run docker-compose up -d for it to take effect.

+
+
+
1
+2
+3
+4
+5
+6
+7
+8
version: "3.2"
+
+services:
+
+  front:
+    volumes:
+#      - /opt/seat-docker/custom/custom-layout-mini.css:/var/www/seat/public/custom-layout-mini.css
+#      - /opt/seat-docker/custom/custom-layout.css:/var/www/seat/public/custom-layout.css
+
+

Once you have placed the files you will need to run docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d for it to take effect.

+
+
+
1
+2
+3
+4
+5
+6
+7
+8
version: "3.2"
+
+services:
+
+  front:
+    volumes:
+#      - /opt/seat-docker/custom/custom-layout-mini.css:/var/www/seat/public/custom-layout-mini.css
+#      - /opt/seat-docker/custom/custom-layout.css:/var/www/seat/public/custom-layout.css
+
+

Once you have placed the files you will need to run docker-compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d for it to take effect.

+
+
+
+

An example of a customized login page using custom-layout-mini.css would be:

+
+

Note

+

Valid corporations or alliances ids in the URL can be used for login.logo::before section.

+
+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
/**
+ * SeAT login page layout
+ */
+@media all {
+    html, body {
+        height: auto;
+    }
+
+    .login-page, .register.body {
+        color: rgb(255,255,255);
+        background-image: url(https://web.ccpgamescdn.com/aws/eveonline/sso/background.jpg);
+        background-position: center center;
+        background-repeat: no-repeat;
+        background-size: cover;
+        background-attachment: fixed;
+    }
+
+    .login-box, .register-box {
+        width: 360px;
+        margin: 0;
+        position: absolute;
+        top: 50%;
+        left: 50%;
+        background: rgba(48,48,48,.8);
+        transform: translate(-50%, -50%);
+        border: 5px solid #ecf0f1;
+        border-radius: 40px;
+        box-shadow: 0 1px 1px rgba(0,0,0,0.05);
+    }
+
+    .login-logo, .register-logo {
+        font-size: 35px;
+        text-align: center;
+        margin-bottom: 25px;
+        font-weight: 300;
+        margin-top: 50px;
+    }
+
+    .login-logo::before, .register-logo::before {
+        content: " ";
+        display: block;
+        width: 128px;
+        height:128px;
+        margin: 0 auto;
+        background-image: url(https://images.evetech.net/corporations/98482334/logo?size=128);
+        border-radius: 50%;
+        margin-bottom: 50px;
+    }
+
+    .login-box-body, .register-box-body {
+        background: transparent;
+        padding: 20px;
+        border-top: 0;
+        color: inherit;
+    }
+}
+
+

The above code will create the login page below:

+

Customized Login Page

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/troubleshooting/index.html b/troubleshooting/index.html new file mode 100644 index 00000000..8ac47a0a --- /dev/null +++ b/troubleshooting/index.html @@ -0,0 +1,1633 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Troubleshooting - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Troubleshooting

+

So the inevitable happened. Something broke or simply isn't working as expected! That's OK. Usually its possible to recover from almost any type of error. The only thing that you can't recover from is not making database backups!

+

There are a few things you can do to perform general troubleshooting. These range from flipping SeAT into debug mode to simply running a self diagnostics command. Lets take a look at a few steps you can take:

+

Whoops

+
+

Whoops, looks like something went wrong.

+
+

whoops

+

The dreaded "Whoops" message has appeared and now you need to figure out why. Normally, this means that something serious broke and the application simply can't recover by itself. In many cases it could either be a quick fix you can do yourself, or something that could result in the need to fix some code.

+

In either case, the next steps to perform when seeing this would be to either enable debug mode and reloading the page / request that failed, or by viewing the log file while retrying the failed request.

+

Memory Errors

+
+

Fatal error: Allowed memory size of #### bytes exhausted (tried to allocate 4096 bytes)...

+
+

If you are presented with an error below similar to this after "Updating Dependencies" you must append your .ENV file with COMPOSER_MEMORY_LIMIT= -1 and restart the stack with the following if you are using docker:

+
+
+
+
docker-compose up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+
+

Note

+

Note: spacing is important for this parameter, if you are unsure copy/paste the needed line into your .ENV file.

+
+

Enabling Debug Mode

+

Debug mode controls how much information about an error condition is displayed to the user. When debug mode is enabled, the error message will be extremely verbose, whereas when its disabled, it simply states that an error had occurred. In either case, the error will always be written to the logs. By default, SeAT does not have debug mode enabled. There are many reasons for this with the primary reason being security related. It goes without saying that once you have completed debugging and fixing your instance, always make sure you disable debug mode afterwards.

+

Once you have enabled debug mode, any errors that may occur would look something like the following instead of the default "Whoops" message. Depending on if you have development packages installed (which you wouldn't by default in non-development installations), the debug page may look slightly different.

+

debugerror

+

Irrespective of how you installed SeAT, enabling debug mode is always a matter of changing the APP_DEBUG configuration option in the .env to `true. However, for it to apply depends on how you installed, so follow the appropriate steps below.

+

Debug Mode - Host Installs

+

Assuming you installed SeAT on your host using either the SeAT tool or manually, cd to your SeAT installation directory. If you followed the guides on this documentation website, that would be in /var/www/seat. Next, open the .env file in a text editor and modify the line that says APP_DEBUG=false to say APP_DEBUG=true.

+

The change would immediately take effect and you can simply reload the failed request for a detailed error message and code stack trace.

+

Debug Mode - Docker Installs

+

If you installed using Docker, cd to the directory where the docker-compose.yml file is located. Assuming you followed the guides on this website, that would be in /opt/seat-docker. Next, open the .env file in a text editor and modify the line that says APP_DEBUG=false to say APP_DEBUG=true.

+

For the change to take effect, you need to reload the stack:

+
+
+
+
docker-compose up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+
+
+
+

The containers will take a few moments to settle down after which you can reload the failed the request for a detailed error message and code stack trace.

+

Checking Log Files

+

Logs are always written to one of two log files irrespective of whether the application is in debug mode or not. Application logs go to the Laravel frameworks log files. API requests sent to ESI are stored int he Eseye log file. Logs are stored in the applications storage directory which can be found in the storage/logs folder.

+

Assuming you followed the guides on this documentation site, the full path to the directory where log files are will be /var/www/seat/storage/logs/. In the case of Docker installations, this will also be the path within the seat-web/front or seat-worker/worker container. Log files are rotated daily and are kept for a maximum of 10 days by default. Therefore, to get to todays application logs, the log file itself may be called laravel-2018-05-31.log. To find today's ESI requests logs, the log file will be called eseye-2018-05-31.log.

+

Live Logs - Host Installs

+

Irrespective of which log file you want to look at, getting todays live logs written to screen can be done with the following commands:

+

Application Logs:

+
tail -f /var/www/seat/storage/logs/laravel-$(date +%Y-%m-%d).log
+
+

Esye / ESI Logs:

+
tail -f /var/www/seat/storage/logs/eseye-$(date +%Y-%m-%d).log
+
+

Live Logs - Docker Installs

+

Application source code and log files are shared between the seat-web/front, seat-worker/worker and seat-cron/scheduler containers. Therefore, the following commands can be executed on any of those containers. For purposes of demonstration, we are going to tail the logs from the seat-web/front container.

+

First, enter get a shell within the seat-web/front container while in the /opt/seat-docker/ directory with:

+
+
+
+
docker-compose exec seat-web sh
+
+
+
+
docker compose exec front sh
+
+
+
+
+

Next, tail the log files you want to see.

+

Application Logs:

+
tail -f /var/www/seat/storage/logs/laravel-$(date +%Y-%m-%d).log
+
+

Esye / ESI Logs:

+
tail -f /var/www/seat/storage/logs/eseye-$(date +%Y-%m-%d).log
+
+

Diagnose command

+

A diagnostics command exists that aims to perform a number of self-checks to help you diagnose problems. This command should be run as the same user the SeAT workers are running as, which is typically either www-data on Ubuntu / Debian based systems and nginx on CentOS based systems. If you have created yourself a separate user for SeAT, then running the diagnose command as that user is what you need to do.

+

Diagnose - Host Installs

+

Host installs require you to first cd to the directory where you installed SeAT. If you followed the guides on this website, that would be /var/www/seat. Next, run the diagnose command as the user you are running the workers as. If you are the root user, you can run it with:

+
su -c 'php artisan seat:admin:diagnose' -s /bin/sh www-data
+
+

Diagnose - Docker Installs

+

For Docker installations, the only requirement to run the diagnose command would be to ensure that you are currently in the same folder as that where the stacks docker-compose.yml file lives. If you followed the guides on this website that would be in /opt/seat-docker. Next, run the command with:

+
+
+
+
docker-compose exec seat-web su -c 'php artisan seat:admin:diagnose' -s /bin/sh www-data
+
+
+
+
docker compose exec front su -c 'php artisan seat:admin:diagnose' -s /bin/sh www-data
+
+
+
+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/from_seat_1_0/index.html b/upgrading/from_seat_1_0/index.html new file mode 100644 index 00000000..15abcc50 --- /dev/null +++ b/upgrading/from_seat_1_0/index.html @@ -0,0 +1,1663 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + From SeAT 1.0 - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

SeAT 1.0 to 2.0

+

The upgrade path from SeAT 1.x to SeAT 2.0 requires some manual work. This is mainly due to the number of fundamental changes that were made in the SeAT 2.x release.

+

Notes on the upgrade

+

The way SeAT is structured has not changed much since its version 1x days. The biggest change is a Laravel framework upgrade to version 5.3. This introduced a new base layout for the application which is why the manual upgrade is needed.

+

The upgrade process has a large amount of database migrations that need to run so grab a coffee depending on how big your database is!

+

Requirements

+
    +
  • SeAT 2.0 requires PHP 7.0. At the time of writing this document, PHP 7.1 is not supported due to bug in PhealNG (the component SeAT uses to talk to the EVE API).
    • +
  • MySQL 5.7 is recommended but not required.
    • +
  • A database backup is an absolute must. Everything in SeAT can be recovered is some way or form except for your database. Make 100% sure you backed this up before proceeding with the upgrade!
    • +
  • Take note of where SeAT is installed. This is usually in /var/www/seat.
    • +
+

Upgrade procedure

+

Preparation

+

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely). Its therefore recommended that you start by putting SeAT into maintenance mode before starting the upgrade. Do this by running the following command in your SeAT path.

+
1
+2
$ cd /var/www/seat
+$ php artisan down
+
+

You should see the message Application is now in maintenance mode..

+

Backups

+
    +
  • Make a backup of your SeAT database and store it somewhere safe! Do not skip this step!
    • +
  • In your SeAT directory, make a copy of the .env file. This file contains all of your SeAT configuration. These values are needed to reconnect to the database once SeAT 2.0 is installed.
    • +
+

Php 7

+

Install PHP7 if you don't have it already. You can check your PHP version by running php -v:

+
1
+2
+3
+4
$ php -v
+PHP 7.0.14 (cli) (built: Dec  7 2016 10:25:25) ( NTS )
+Copyright (c) 1997-2016 The PHP Group
+Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
+
+

Get the new code

+

SeAT 2.0 can be installed in exactly the same place as where you had your v1.x installation. If you reuse this path then no webserver re-configuration will be needed. We will move the old installation out of the way, and install SeAT 2.0. To do this, run the following commands:

+
    +
  • First, move the old installation out of the way:
    • +
+
1
+2
$ cd /var/www
+$ mv seat seat.old
+
+

You can double check that this was successful by running ls and ensuring that there is a folder named seat.old now.

+
    +
  • Next, get the new SeAT code by running composer create-project eveseat/seat seat --no-dev:
    • +
+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
$ cd /var/www
+$ composer create-project eveseat/seat seat --no-dev
+Installing eveseat/seat (2.0.0)
+  - Installing eveseat/seat (2.0.0)
+    Loading from cache
+
+Created project in seat
+> php -r "file_exists('.env') || copy('.env.example', '.env');"
+Loading composer repositories with package information
+Updating dependencies
+
+[ ... snip ... ]
+
+

Publish the assets

+

Next, we need to publish the new SeAT 2.0 CSS & Javascript and database migrations. This can be done with php artisan vendor:publish --force.

+

Reconfigure .env file

+

With the new code ready to use, the next thing that is required is to reconnect the database. Remember that .env file you backed up earlier? Refer to it for the values needed in the newly installed env file that can be found at /var/www/seat/.env.

+

Important keys to populate with the correct values are:

+
1
+2
+3
+4
+5
DB_HOST=
+DB_PORT=
+DB_DATABASE=
+DB_USERNAME=
+DB_PASSWORD=
+
+

SeAT 2.0 introduced new configuration items in the .env that you can review. There is also the option to configure Supervisor & SeAT integration, which can be done by following the admin guide titled SeAT & Supervisor Integration.

+

Run migrations

+

With the database reconnected, its time to run the migrations for SeAT 2.0. This is the part that may take some time, depending on how big your database is.

+

To run the migrations, make sure you are still in your seat path (/var/www/seat) and run php artisan migrate:

+
1
+2
$ cd /var/www/seat
+$ php artisan migrate
+
+

You will see a bunch of messages and eventually your shell prompt again, indicating that it has completed. If you receive errors here, double check that you have entered the correct database settings in the .env file previously mentioned.

+

Database seeders

+

With the database migration complete, its time to seed it with some of the static data SeAT needs. Do this with the following commands:

+
1
+2
+3
php artisan db:seed --class=Seat\\Notifications\\database\\seeds\\ScheduleSeeder
+php artisan db:seed --class=Seat\\Services\\database\\seeds\\NotificationTypesSeeder
+php artisan db:seed --class=Seat\\Services\\database\\seeds\\ScheduleSeeder
+
+

Update worker jobs

+

The Laravel 5.3 upgrade in SeAT changed the way worker jobs are started. You can edit the command used to start a worker in your seat.conf file in supervisor. Normally, this file will be somewhere like in /etc/supervisor/conf.d/.

+

The only line you really need to edit is the one that starts with command, replacing it with:

+
command=/usr/bin/php /var/www/seat/artisan queue:work --queue=high,medium,low,default --tries 1 --timeout=86100
+
+

A full block for SeAT 2.0 should therefore be:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
[program:seat]
+command=/usr/bin/php /var/www/seat/artisan queue:work --queue=high,medium,low,default --tries 1 --timeout=86100
+process_name = %(program_name)s-80%(process_num)02d
+stdout_logfile = /var/log/seat-80%(process_num)02d.log
+stdout_logfile_maxbytes=100MB
+stdout_logfile_backups=10
+numprocs=4
+directory=/var/www/seat
+stopwaitsecs=600
+user=www-data
+
+
+

Note

+

Keep in mind the user value and the path to artisan should be correct. +Update them to the correct values of you made changes to the defaults. +The user value differs many times based on Linux distribution too!

+
+

Finishing off

+

With all of that done, bring your application back up with php artisan up and start the supervisor workers again. +Watch the logs for any errors in case things have not gone as expected. +If you need any help, feel free to join the Slack channel details in the Contact page on the left.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/from_seat_2_0/index.html b/upgrading/from_seat_2_0/index.html new file mode 100644 index 00000000..15080ff2 --- /dev/null +++ b/upgrading/from_seat_2_0/index.html @@ -0,0 +1,1492 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + From SeAT 2.0 - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

SeAT 2.0 to 3.0

+

The upgrade path from SeAT 2.x to SeAT 3.0 requires some manual work. This is mainly due to the number of fundamental database changes that were made in SeAT 3.x.

+

Notes on the upgrade

+

Most of the database has been revamped to match ESI models. Therefore, we can't offer you a simple update as we do for minor patches. However, once migrated, updates can be done as per usual.

+

The process described bellow handles data conversion between the SeAT 2.x structure and SeAT 3.x one.

+

Requirements

+
    +
  • Check SeAT 3.0 Requirements
    • +
  • A database backup is an absolute must. Everything in SeAT can be recovered is some way or + form except for your database. Make 100% sure you backed this up before proceeding with the upgrade!
    • +
  • Enough storage space to contains SeAT 2, SeAT 3, a backup of SeAT 2 database and a backup of SeAT 3 database.
    • +
  • Take note of where SeAT 2 is installed. This is usually in /var/www/seat.
    • +
+

Upgrade procedure

+

Preparation

+

If users are using your SeAT instance, or the workers are churning away in the background, then you may +risk losing some information (although unlikely). Its therefore recommended that you start by putting +SeAT into maintenance mode before starting the upgrade. Do this by running the following command in your SeAT path.

+
php artisan down
+
+

If you are running this migration after CCP killed the XML API then there is probably no risk of the updaters doing anything useful anyways :D

+

Backups

+
    +
  • Make a backup of your SeAT database and store it somewhere safe! Do not skip this step!
    • +
  • In your SeAT directory, make a copy of the .env file. This file contains all of your SeAT configuration. These values may be useful in case of failure.
    • +
+

Installing SeAT 3.0

+

Rename the current SeAT directory from /var/www/seat to /var/www/seat2. +You don't have to update any config since we will only use the command line for the process. +mv /var/www/seat /var/www/seat2

+

Follow standard installation instructions for SeAT 3.0.

+
+

Warning

+

You need to keep the current SeAT 2.0 installed in order to migrate data to a newly installed 3.0 instance. +It doesn't have to be reachable from internet though since we will only use the command line for the process.

+
+

Installing the migrator package on SeAT 2.0

+
    +
  • Move to your SeAT 2.0 installation directory (should be /var/www/seat2 - unless you changed it)
    • +
  • Add the package called seat-migrator using composer require warlof/seat-migrator
    • +
  • Edit the app.php file inside the config folder by appending Warlof\Seat\Migrator\MigratorServiceProvider::class, to the end of providers array.
    • +
  • Once done, publish the package files using php artisan vendor:publish --force
    • +
  • Run migration scripts with php artisan migrate
    • +
  • Finally, run php artisan seat:migrator:upgrade and follow the wizard
    • +
+

At the end of the process, you will have most of your data transferred into the specified SeAT 3.0 database. +Next, you can remove the seat2 directory with rm -R /var/www/seat2 and the old database.

+

Enjoy SeAT 3.0

+
+

Note

+

In case of any troubles, the migrator package did a backup before starting the migration process. +The output is specified in the prompt while it is being done, but you will also find it in /var/www/seat2/storage/backup.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/from_seat_3_0/bare_metal/index.html b/upgrading/from_seat_3_0/bare_metal/index.html new file mode 100644 index 00000000..17e2dd90 --- /dev/null +++ b/upgrading/from_seat_3_0/bare_metal/index.html @@ -0,0 +1,1651 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Bare metal - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT 3.0 to 4.0 (Bare metal)

+

The upgrade path from SeAT 3.0 to SeAT 4.0 requires some manual work. This is primarily due to large amounts of refactoring that made it into SeAT 4.

+
+

Info

+

Major changes have been made to the way packages workg together, especially the eveapi, web and services packages.

+

The way jobs are queued and queues themselves have also changed, mostly to reduce resource usage and to improve fluency.

+

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 4. If you are unsure, join us on Slack so that we can tru and assist or redirect you to proper person.

+
+
+

Warning

+

Before you do anything, read and understand this entire upgrade guide.

+

Those instructions are valid for bare metal deployment only (non-docker installation). +Please refer to docker instructions for a Docker installation.

+

Remember to do a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

+
+

Requirements

+
    +
  • Check SeAT 4.0 requirements
    • +
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
    • +
  • Enough storage space to have SeAT 3, SeAT 4 and a backup of your SeAT 3 database.
    • +
  • Ensure all your SeAT 3 packages are up-to-date (check this in Settings > SeAT Settings)
    • +
+

Upgrade Procedure

+

Preparation

+

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely) - or cause crash during database conversion. +Please start to turning SeAT in maintenance mode, cutting jobs and clearing caches before starting the upgrade.

+

Turn workers down, use the command

+
service supervisor stop
+
+

Put SeAT in maintenance mode

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan down'
+
+

Clear cache

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:cache:clear'
+
+

Backups

+
    +
  • Make a backup of your SeAT database and store it somewhere safe! Do no skip this step!
    • +
  • In your SeAT directory, make a copy of the .env file. +This file contains all your SeAT configuration, including tokens watermark required to update your registered users content. +These values might be useful in case of failure.
    • +
+

Installing SeAT 4.0

+

Rename the current SeAT directory from /var/www/seat to /var/www/seat3. +You don't have to update any config since we will only use the command line for the process.

+
mv /var/www/seat /var/www/seat3
+
+

PHP

+

If it's not already the case, you'll have to deploy at least PHP 7.3 on the server. +The provided command bellow will help you in this task and add newly required PHP extensions in the meantime.

+
1
+2
+3
apt-get update
+apt-get install libpng-dev libfreetype6-dev libjpeg-dev
+apt-get install curl openssl zip php7.3-bz2 php7.3-cli php7.3-curl php7.3-dom php7.3-gd php7.3-gmp php7.3-intl php7.3-mbstring php7.3-mysql php7.3-opcache php7.3-redis php7.3-zip
+
+

Remember to update your NGinX configuration to use the new CGI version. To do so, open configuration file located at /etc/nginx/sites-available/seat and replace

+
       fastcgi_pass unix:/run/php/php7.1-fpm.sock;
+
+

with

+
       fastcgi_pass unix:/run/php/php7.3-fpm.sock;
+
+

SeAT

+

Once packages have been updated, we will deploy the new SeAT's version using composer.

+
composer create-project eveseat/seat /var/www/seat "4.0.*" --no-dev --no-interaction
+
+

Once the download is done, you should have seen output such as:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
Writing lock file
+Generating optimized autoload files
+> Illuminate\Foundation\ComposerScripts::postAutoloadDump
+> @php artisan package:discover
+Discovered Package: darkaonline/l5-swagger
+Discovered Package: eveseat/api
+Discovered Package: eveseat/console
+Discovered Package: eveseat/eveapi
+Discovered Package: eveseat/notifications
+Discovered Package: eveseat/services
+Discovered Package: eveseat/web
+Package manifest generated successfully.
+> @php artisan key:generate
+Application key [base64:CmhqYNkaIcHo8nYC8LiEWa3U5/+BiTLih5dZftxlV2k=] set successfully.
+
+

Finally, fix directories permissions using the two commands bellow:

+
1
+2
chown -R www-data:www-data /var/www/seat
+chmod -R guo+w /var/www/seat/storage/
+
+

Setup

+

Now sources have been deployed, we have to update .env configuration file. +Use information from backup located at /var/www/seat3/.env to update the newly generated file located at /var/www/seat/.env.

+
+

Info

+

In case you had third party packages installed, it's time to deploy them back. +We invite you to report to their own documentation regarding any specific guideline.

+
+
+

Warning

+

Please pay special attention to APP_KEY, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, +DB_PASSWORD, EVE_CLIENT_ID, EVE_CLIENT_SECRET and EVE_CALLBACK_URL parameters.

+
+

Database

+

We will convert database to work with new SeAT version. To do so, we're using common commands disclosed bellow:

+
1
+2
+3
+4
sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'
+sudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'
+sudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\Console\\database\\seeds\\ScheduleSeeder'
+sudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde --force'
+
+

Complete

+

Finally, restore workers states and put SeAT online using initial commands in reverse order.

+

Put SeAT online

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan up'
+
+

Convert user tokens format from previous version

+
sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:token:upgrade'
+
+

Turn workers up

+
service supervisor start
+
+

Access

+

SeAT 4.0 is coming with a complete revamp of permissions system. As a result, your previous roles haven't been converted. +However, they've been keep - so you can configure them with the new system.

+

You will have to use built-in admin account for your first connexion.

+
+

Info

+

Super administrator is now an user flag and have to be defined at user level instead of Access Permissions. +You'll get more information regarding the new system on Admin Login and Authorizations pages.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/from_seat_3_0/docker/index.html b/upgrading/from_seat_3_0/docker/index.html new file mode 100644 index 00000000..6b2179d3 --- /dev/null +++ b/upgrading/from_seat_3_0/docker/index.html @@ -0,0 +1,1983 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Docker - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT 3.0 to 4.0 (Docker)

+

The upgrade path from SeAT 3.0 to SeAT 4.0 requires some manual work. This is primarily due to large amounts of refactoring that made it into SeAT 4.

+
+

Info

+

Major changes have been made to the way packages workg together, especially the eveapi, web and services packages.

+

The way jobs are queued and queues themselves have also changed, mostly to reduce resource usage and to improve fluency.

+

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 4. If you are unsure, join us on Slack so that we can tru and assist or redirect you to proper person.

+
+
+

Warning

+

Before you do anything, read and understand this entire upgrade guide.

+

Those instructions are valid for Docker deployment only. +Please refer to bare metal instructions for a non-docker installation.

+

Remember to do make a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

+
+

Requirements

+
    +
  • Check SeAT 4.0 requirements
    • +
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
    • +
  • Enough storage space to have SeAT 3, SeAT 4 and a backup of your SeAT 3 database.
    • +
  • Ensure all your SeAT 3 packages are up-to-date (check this in Settings > SeAT Settings)
    • +
+

Docker Upgrade Procedure

+

If you are currently using a docker installation for SeAT 3, you are in for a treat because upgrading is super easy. All we are going to do is bring the v4 stack up, connect your database and watch as the Docker entrypoint takes care of the rest.

+

This guide is going to step through some quick preparation steps, then perform the upgrade and finally, check that everything worked out as expected. Let's dive in.

+

tl;dr upgrades

+

We highly reccomend that you read the details of this upgrade guide to get familiar with what has changed. But, if this is your nth upgrade, maybe you just want to get the summary of everything, so here it is:

+
    +
  • Make a backup of your database.
    • +
  • cd to your install dir (which is probably /opt/seat-docker) and bring the stack down with docker-compose down
    • +
  • Make a copy of your .env and docker-compose.yml files.
    • +
  • Download the new docker-compose.yml file with curl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -o docker-compose.yml.
    • +
  • Down the new .env file with curl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -o .env.
    • +
  • Upgrade your docker-compose installation. It should be version 1.26 and up.
    • +
  • Configure the new .env file. Important configs include the TRAEFIK_ variables, the SEAT_SUBDOMAIN variable. Copy over existing values from your old .env file for the EVE_CLIENT_ variables, the APP_KEY varaible and finally the DB_ variables.
    • +
  • Bring the stack back up with docker-compose up -d and watch the migration process.
    • +
  • Finally, once the migration process is complete, update the EVE SDE to populate the tables with static data with: docker-compose exec seat-web php artisan eve:update:sde --force -n
    • +
+

🎉

+

Docker changes since SeAT 3

+

A number of changes have been made how the docker-compose stack is glued together.

+

First, the docker repository for SeAT 4 has a new home here, and a new image here.

+

In SeAT 3, services such as web, workers and cron were all using seperate images. For SeAT 4, we have consilidated all of that into a single image, with a service-aware entrypoint. The code for all of this lives in a new dedicated repository instead of being "hidden" away in the script repo here. All of these changes also mean that we now have the ability to properly tag the docker images instead of relying on the latest tag like we did in SeAT 3. Finally.

+

Next, the default nginx web server has been replaced with Traefik. For the majority of users this means little to no change to what you were used to. However, if you were fronting your instance with another reverse proxy, it is important to be aware of this change. The base image used for the SeAT docker image uses apache2 to serve the web UI, and Traefik reverse proxies to this, exposing it to the world. Advanced users can rip this out, expose the apache server directly and continue using the setup you have. The options are limitless.

+

Preperation

+

Before you upgrade, you need to backup.

+

Backup your database

+

The single most important thing you need is a backup of your SeAT 3 database. Without a backup you will not be able to recover in case of a disaster. So, head on over to the docker db backup section and do that right now.

+

Backup your env file

+

The .env file is the one that has your SeAT installations' configuration. It contains things like your SSO Client ID and Secret (aka: credentials). By default, SeAT docker installations live in /opt/seat-docker meaning your .env file will be at /opt/seat-docker/.env. Make a copy of this file and store it somewhere safe.

+

Upgrade docker-compose

+

The docker-compose binary should be upgraded so that we can make use of ${VARIABLES} inside .env files.

+

If you installed docker-compose using your OS' package manager, upgrade the tool using that. Otherwise, a curl invocation to download the latest version should also work.

+
1
+2
curl -L https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
+chmod +x /usr/local/bin/docker-compose
+
+

Stop SeAT 3

+

First, we need to stop the SeAT 3 stack. Assuming you have the default /opt/seat-docker location for your installation, cd to it first and then run:

+
docker-compose down
+
+

The output should be similar to this:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
root@seat:/opt/seat-docker# docker-compose down
+Stopping seat-nginx   ... done
+Stopping seat-cron    ... done
+Stopping seat-worker  ... done
+Stopping seat-app     ... done
+Stopping seat-mariadb ... done
+Stopping seat-redis   ... done
+Removing seat-nginx   ... done
+Removing seat-cron    ... done
+Removing seat-worker  ... done
+Removing seat-app     ... done
+Removing seat-mariadb ... done
+Removing seat-redis   ... done
+Removing network seat-docker_seat-network
+
+

Upgrading to SeAT 4

+

Get the new docker-compose file

+
+

Warning

+

If you have made customisations to how you deployed SeAT with docker-compose, then you should probably not be replacing the compose file like we are about to do. Instead, have a look at the new one here and adapt.

+
+

Next, we will download the new SeAT 4 docker-compose file. Do that with:

+
1
+2
mv docker-compose.yml docker-compose.yml.back
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/docker-compose.yml -o docker-compose.yml
+
+

With this we have created a copy of the older docker-compose file (just in case), and downloaded the new one.

+

Get the new .env file

+

The next step is to get a fresh copy of the new .env file to use together with the new docker-compose setup. There have been a number of changes to this file (primarily as a result of the web server swap out) which we will describe in the next section.

+

Get it with:

+
1
+2
mv .env .env.back
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/4.x/.env -o .env
+
+

Configure the new .env file

+
+

Info

+

This is admitedly the hardest part of the migtation, so pay close attention. Take it slowly and think about what you are doing here.

+
+

There are four main settings categories that need to be updated in the new .env file. Those are:

+
    +
  • Traefik (webserver)
    • +
  • EVE Online SSO Config
    • +
  • The application key
    • +
  • Database credentials
    • +
+

All of these categories will be described below in detail. For all of them, you have to open the newly downloaded .env file in a text editor and update the values. To be sure you are editing the correct file, check its header. It should say:

+
1
+2
+3
+4
+5
+6
+7
+8
# SeAT Docker Compose Configuration
+
+# Web server configuration.
+# SeAT running in a docker-compose setup ships with Traefik
+# as the default web server. You only need to configure the
+# parent domain and port where the web server will listen.
+# In most cases, just configuring the domain will be all
+# you need to do.
+
+
Traefik
+

As mentioned earlier. The web server has been swapped out in favour of Traefik. As a result, you need to set a few configuration options to get the web UI to work. If you have a setup where you have configured something like nginx outside of your Docker installation, we highly reccomend you just remove that and switch over to Traefik. Of anything, it's handling of TLS with Let's Encrypt is quite literally a one-time setup and forget thing.

+

Inside the .env file, Traefik specific configuration options are prefixed with TRAEFIK_. They are:

+
1
+2
+3
+4
TRAEFIK_DOMAIN=seat.local
+TRAEFIK_HTTPS_PORT=443
+TRAEFIK_HTTP_PORT=80
+TRAEFIK_ACME_EMAIL=you@domain.com
+
+

These fields need to be updated as follows:

+
    +
  • TRAEFIK_DOMAIN: This is the base domain where your SeAT installation lives. For example, if your SeAT 3 installation lives at seat.domain.com, you enter domain.com here.
    • +
  • TRAEFIK_HTTPS_PORT: This is the external port that will be open to the world. SeAT 4 in docker with Traefik will only listen on TLS as well. Since its configured to be 443, it will most likely clash with your external web server. We reccomend that you just disable your external web server and use Traefik. TLS configuration with it is a breeze!
    • +
  • TRAEFIK_HTTPS_PORT: This is the non-TLS port that Let's Encrypt (as part of the ACME protocol) will connect to during certificate renewals. SeAT will not be available here.
    • +
  • TRAEFIK_ACME_EMAIL: The email address used for Let's Encrypt certificate renewals.
    • +
+

A SEAT_SUBDOMAIN value is also present, which sets the subdomain where the SeAT web UI lives. This value needs to match what your SeAT 3 installation used, especially so that the existing SSO application you have configured on the EVE SSO portal matches the configured callback url.

+

By default, most folks will only configure the domain, subdomain and email and be done. Of course, if you have custom configurations and needs, feel free to adapt.

+
Traefik - TLS
+

Traefik should handle all of the relevant configuration to get your site to listen with a valid TLS certificate. The secrets for the TLS configuration in Traefik relies on an acme.json file which you should mount into the Traefik container from the outside so that it persists restart.

+

Prepare the json file from within /opt/seat-docker with:

+
1
+2
+3
mkdir acme
+touch acme/acme.json
+chmod 600 acme/acme.json
+
+

Next, make sure you have the TRAEFIK_ACME_EMAIL variable set, and finally, uncomment the labels that will make use of the Let's Encrypt cert resolver in the docker-compose.yml file. By default, they will look like this, whereby you need to remove the # in front.

+

(Note: the line below in docker-compose.yml is located in two places, only remove the # from seat-web)

+
#- "traefik.http.routers.seat-web.tls.certResolver=primary"
+
+
EVE Online SSO
+

Since SeAT's authentication relies on EVE's SSO, you need to configure the relevant client id and secret. You can find your old values in the backup you have made of the .env file. The values you need to set are:

+
    +
  • EVE_CLIENT_ID
    • +
  • EVE_CLIENT_SECRET
    • +
+

For the callback URL, ensure that you have correctly configured the SEAT_SUBDOMAIN value in the previous step.

+
The SeAT Application Key
+

By default, the APP_KEY value for a fresh .env file will be insecure. This is a purposefully incorrectly formatted value. You can simply set this to the value you have for the same variable in your backup .env file.

+
Database details
+

This is one of the more important steps. The database configuration needs to match what your SeAT 3 installation used because the database data lives in a docker volume. When the stack will start up for the first time again, the SeAT 4 container will have access to the SeAT 3 database volume, and run migrations there. So, you need to copy the database credentials from the old .env file to the new one.

+

The variable names have remained unchanged, but for referece they are:

+
1
+2
+3
+4
DB_DATABASE=seat
+DB_USERNAME=seat
+DB_HOST=mariadb
+DB_PASSWORD=i_should_be_changed
+
+

Bringing SeAT 4 up

+

The only thing that is left to do is to start the stack up again. The first time we are goin to start SeAT 4 we wont use the -d flag. This is just so that you can see what's happening during the upgrade procedure. So, start SeAT with:

+
docker-compose up
+
+

You should see something like this happen when you run the above command:

+
1
+2
+3
+4
+5
+6
+7
+8
+9
root@seat:/opt/seat-docker# docker-compose up
+Creating network "seat-docker_seat-network" with the default driver
+Pulling mariadb (mariadb:10)...
+10: Pulling from library/mariadb
+3ff22d22a855: Already exists
+e7cb79d19722: Already exists
+323d0d660b6a: Already exists
+
+...
+
+

After a while, migrations should start running:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
...
+
+seat-web_1     | starting web service
+seat-web_1     | Starting first run routines
+seat-web_1     | Migrating: 2018_06_05_110000_drop_assets_from_outposts
+seat-web_1     | Migrated:  2018_06_05_110000_drop_assets_from_outposts (0.02 seconds)
+seat-web_1     | Migrating: 2019_02_09_110731_drop_type_from_notification_groups
+seat-web_1     | Migrated:  2019_02_09_110731_drop_type_from_notification_groups (0.01 seconds)
+seat-web_1     | Migrating: 2019_05_11_164831_add_permission_role_filter
+
+...
+
+
+

Warning

+

Do not interrupt the database migration phase. It will leave your database in a potentially corrupt state, meaning you are going to have to do some extra pluming to get a backup restored. Not a train smash, but not worth it.

+
+

Be patient, there are many, many database changes that need to apply.

+

Eventually, when everything is done you should start seeing the following output:

+
1
+2
+3
+4
seat-worker_1  | [2020-08-19 21:11:45][2] Processing: Seat\Eveapi\Jobs\Status\Status
+seat-worker_1  | [2020-08-19 21:11:45][1] Processing: Seat\Eveapi\Jobs\Status\Esi
+seat-worker_1  | [2020-08-19 21:11:46][2] Processed:  Seat\Eveapi\Jobs\Status\Status
+seat-worker_1  | [2020-08-19 21:11:46][1] Processed:  Seat\Eveapi\Jobs\Status\Esi
+
+

This is a good sign, and means everything is now ready!

+

Check your installation

+

The first obvious step will be to check that you can access the web UI. If not, something is probably weird with the web server configuration and needs some tweaking.

+

If everything seems to be working fine, you can hit crtl + c which will bring the stack down gracefully.

+
1
+2
+3
+4
+5
+6
^CGracefully stopping... (press Ctrl+C again to force)
+Stopping seat-docker_seat-cron_1   ...
+Stopping seat-docker_seat-worker_1 ...
+Stopping seat-docker_seat-web_1    ...
+Stopping seat-docker_traefik_1     ... done
+Stopping seat-docker_redis_1       ...
+
+

Then, bring it back up with the -d flag.

+
docker-compose up -d
+
+

Convert User Tokens

+

SeAT 4.x is using the new CCP Token format (v2). In order to use registered tokens from your previous installation, +you'll have to run the following command:

+
docker-compose exec seat-web php artisan seat:token:upgrade
+
+

Update EVE SDE

+

This is the final step, for real. You need to update the EVE SDE. With your stack up and running (after executing docker-compose up -d), you can now force an SDE update with:

+
docker-compose exec seat-web php artisan eve:update:sde --force -n
+
+

Congrats, and welcome to SeAT 4!

+
+

Info

+

Super administrator is now an user flag and have to be defined at user level instead of Access Permissions. +You'll get more information regarding the new system on Admin Login and Authorizations pages.

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/from_seat_4_0/bare_metal/index.html b/upgrading/from_seat_4_0/bare_metal/index.html new file mode 100644 index 00000000..4e2a1c32 --- /dev/null +++ b/upgrading/from_seat_4_0/bare_metal/index.html @@ -0,0 +1,1624 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Bare metal - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT 4.x to 5.0 (Bare metal)

+

The upgrade path from SeAT 4.0 to SeAT 5.0 requires a tiny amount of manual work.

+
+

Warning

+

Before you do anything, read and understand this entire upgrade guide.

+

Those instructions are valid for bare metal deployment only (non-docker installation). +Please refer to docker instructions for a Docker installation.

+

Remember to do a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

+
+
+

Info

+

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 5. If you are unsure, join us on Discord so that we can assist or redirect you to the proper person.

+
+

Requirements

+
    +
  • Check [SeAT 5.0 requirements]
    • +
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
    • +
  • Enough storage space to have SeAT 5, SeAT 4 and a backup of your SeAT 4 database.
    • +
  • Ensure all your SeAT 4 packages are up-to-date (check this in Settings > SeAT Settings)
    • +
+

Upgrade Procedure

+

Preparation

+

If users are using your SeAT instance, or the workers are churning away in the background, then you may risk losing some information (although unlikely) - or cause crash during database conversion. +Please start to turning SeAT in maintenance mode, cutting jobs and clearing caches before starting the upgrade.

+

Turn workers down, use the command

+
1
systemctl stop supervisor.service
+
+

Put SeAT in maintenance mode

+
1
sudo -H -u www-data bash -c 'php /var/www/seat/artisan down'
+
+

Clear cache

+
1
sudo -H -u www-data bash -c 'php /var/www/seat/artisan seat:cache:clear'
+
+

Backups

+
    +
  • Make a backup of your SeAT database and store it somewhere safe! Do no skip this step!
    • +
  • In your SeAT directory, make a copy of the .env file. + This file contains all your SeAT configuration, including the keys to the ESI tokens required to update your registered users content. + These values might be useful in case of failure.
    • +
+

Installing SeAT 5.0

+

Rename the current SeAT directory from /var/www/seat to /var/www/seat4. +You don't have to update any config since we will only use the command line for the process.

+
1
mv /var/www/seat /var/www/seat4
+
+

PHP

+

SeAT 5 needs PHP 8.2 on the server. +The provided command bellow will help you in this task and add newly required PHP extensions in the meantime.

+
1
+2
+3
apt-get update
+apt-get install libpng-dev libfreetype6-dev libjpeg-dev
+apt-get install openssl zip php8.2-fpm php8.2-bz2 php8.2-cli php8.2-curl php8.2-dom php8.2-gd php8.2-gmp php8.2-intl php8.2-mbstring php8.2-mysql php8.2-opcache php8.2-redis php8.2-zip
+
+

Remember to update your NGinX configuration to use the new CGI version. To do so, open configuration file located at /etc/nginx/sites-available/seat and replace

+
fastcgi_pass unix:/run/php/php7.3-fpm.sock;
+
+

with

+
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
+
+

Restart nginx to load the changes:

+
1
systemctl restart nginx.service
+
+

SeAT

+

Once packages have been updated, we will deploy the new SeAT's version using composer.

+
1
composer create-project eveseat/seat /var/www/seat "5.0" --no-dev --no-interaction
+
+

Once the download is done, you should have seen output such as:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
76 packages you are using are looking for funding.
+Use the `composer fund` command to find out more!
+> @php artisan vendor:publish --tag=laravel-assets --ansi --force
+
+   INFO  Publishing [laravel-assets] assets.  
+
+  Copying directory [vendor/laravel/horizon/public] to [public/vendor/horizon]  DONE
+  Copying directory [vendor/opcodesio/log-viewer/public] to [public/vendor/log-viewer]  DONE
+
+No security vulnerability advisories found.
+> @php artisan key:generate --ansi
+
+   INFO  Application key set successfully.  
+
+

Finally, fix directories permissions using the two commands bellow:

+
1
+2
chown -R www-data:www-data /var/www/seat
+chmod -R guo+w /var/www/seat/storage/
+
+

Setup

+

Now sources have been deployed, we have to update .env configuration file. +Use information from backup located at /var/www/seat4/.env to update the newly generated file located at/var/www/seat/.env.

+
+

Info

+
+

In case you had third party packages installed, it's time to deploy them back. +We invite you to report to their own documentation regarding any specific guideline.

+
+

Warning

+
+

Please pay special attention to APP_KEY, APP_URL, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, +DB_PASSWORD, EVE_CLIENT_ID, EVE_CLIENT_SECRET and EVE_CALLBACK_URL parameters.

+

Database

+

We will convert database to work with new SeAT version. To do so, we're using common commands disclosed bellow:

+
1
+2
+3
+4
sudo -H -u www-data bash -c 'php /var/www/seat/artisan vendor:publish --force --all'
+sudo -H -u www-data bash -c 'php /var/www/seat/artisan migrate'
+sudo -H -u www-data bash -c 'php /var/www/seat/artisan db:seed --class=Seat\\Services\\Database\\Seeders\\PluginDatabaseSeeder'
+sudo -H -u www-data bash -c 'php /var/www/seat/artisan eve:update:sde --force'
+
+

Complete

+

Finally, restore workers states and put SeAT online using initial commands in reverse order.

+

Put SeAT online

+
1
sudo -H -u www-data bash -c 'php /var/www/seat/artisan up'
+
+

Turn workers up

+
1
systemctl start supervisor.service
+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/from_seat_4_0/docker/index.html b/upgrading/from_seat_4_0/docker/index.html new file mode 100644 index 00000000..588b2c7f --- /dev/null +++ b/upgrading/from_seat_4_0/docker/index.html @@ -0,0 +1,1926 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Docker - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT 4.x to 5.0 (Docker)

+

The upgrade path from SeAT 4.0 to SeAT 5.0 requires a tiny amount of manual work.

+
+

Info

+

Before starting the upgrade, pay check the plugins you may be using and ensure that they are compatible with SeAT 5. +A compatibility table can be found on the Community Packages page. +If you are unsure, join us on Discord so that we can tru and assist or redirect you to proper person.

+

Users of recursivetree/seat-info need to follow separate instructions after the migrating the core to seat 5.

+
+
+

Warning

+

Before you do anything, read and understand this entire upgrade guide.

+

Those instructions are valid for Docker deployment only. +Please refer to bare metal instructions for a non-docker installation.

+

Remember to do make a complete backup of your current database making a copy off the server where SeAT runs together with the .env file. Both of these are the only things required to rebuilt your instance in case of failure.

+
+

Requirements

+
    +
  • A database backup is an absolute must. Everything in SeAT can be recovered in some way or form except for your database.
    • +
  • Enough storage space to have SeAT 4, SeAT 5 and a backup of your SeAT 4 database.
    • +
  • Ensure all your SeAT 4 packages are up-to-date (check this in Settings > SeAT Settings)
    • +
+

Docker Upgrade Procedure

+

If you are currently using a docker installation for SeAT 4, upgrading is easy as never before. You need to make a few changes to your docker stack configuration, restart the stack, and you're good to go.

+

This guide is going to step through some quick preparation steps, then perform the upgrade and finally, check that everything worked out as expected. Let's dive in.

+

tl;dr upgrades

+

We highly recommend that you read the details of this upgrade guide to get familiar with what has changed. But, if this is your nth upgrade, maybe you just want to get the summary of everything, so here it is:

+
    +
  • Make a backup of your database.
    • +
  • cd to your install dir (which is probably /opt/seat-docker) and bring the stack down with + 
    docker compose down
+
    • +
  • Make a copy of your .env file using + 
    cp .env .env.seat4.bak
+
    • +
  • Make a copy of your current compose file using + 
    cp docker-compose.yml docker-compose.yml.seat4.bak
+
    • +
  • Download the new docker-compose.yml file with + 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.yml -o docker-compose.yml`
+
    • +
  • Download the new database override docker-compose.mariadb.yml file with + 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.mariadb.yml -o docker-compose.mariadb.yml
+
    • +
  • Download the new traefik override docker-compose.traefik.yml file with + 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.traefik.yml -o docker-compose.traefik.yml
+
    • +
  • Download the new proxy override docker-compose.proxy.yml file with + 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.proxy.yml -o docker-compose.proxy.yml
+
    • +
  • Download the new .env file template using + 
    curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/.env -o .env
+
    • +
  • Update the new .env file using your backup .env.seat4.bak
    • +
+

The table bellow is provided as a variable mapping between SeAT 4.x and SeAT 5.x. You can use it as a reference.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SeAT 4.xSeAT 5.x
TRAEFIK_DOMAIN=seat.localSEAT_DOMAIN=seat.seat.local
SEAT_SUBDOMAIN=seatSEAT_DOMAIN=seat.seat.local
REDIS_HOST=redisREDIS_HOST=cache
PROXY_BACKEND_HTTP_PORT=8080
LOG_LEVEL=error
+
+

Info

+

With SeAT 5.x, there is non longer default database and proxy. You can mix services are your needs. +However, we continue to provide a few default layout usable out of the box as an option.

+
+
+
+
+

In case you want to use Traefik front of SeAT ui container, you'll need to setup the following environment variable: TRAEFIK_ACME_EMAIL. +You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up

+
+
+

In case you want to use a custom reverse proxy front of SeAT ui container, you'll need to setup the new environment variable PROXY_BACKEND_HTTP_PORT. +You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up

+
+
+
+

Since we didn't startup the stack using daemon mode - the overall migration and process is run at front. This will allow you to detect any issue without having a container running in panic mode. +When SeAT will be ready to serve your requests and have successfully been upgrade, you'll see the following output :

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
2023-06-02 09:49:33          ****////////////                                                   
+2023-06-02 09:49:33      ***                 ///                                                   
+2023-06-02 09:49:33   ***                      //                                                 
+2023-06-02 09:49:33   **     **  //   ///        //                                                
+2023-06-02 09:49:33  **      ***  ///             //      ////////@@@@@@@@@@@@@@@(/////@@@//////////
+2023-06-02 09:49:33            **/   ///   /////////     *///&@@@@@@@&/////#@@@@%//%///#@@@@@(///@ 
+2023-06-02 09:49:33  **     *** //////// /                @///////@@///@@@///@@@///@@///@@@@@(///@ 
+2023-06-02 09:49:33  **      ***   ///   //       //      @@@@@////@/////////@@//////////@@@@(///@ 
+2023-06-02 09:49:33   **         ///  //   /     //      *////////@@@///////@@///@@@@@@///@@@(///@ 
+2023-06-02 09:49:33    ***         //// ///    ///                                              
+2023-06-02 09:49:33       ***                ///                                              
+2023-06-02 09:49:33          ****////////////
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 SeAT is now ready to serve requests
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 Open your browser and go to 'https://seat.domain.tld'
+2023-06-02 09:49:33 Run 'docker compose exec front php artisan seat:admin:login' to get a temporary link in order to sign-in as built-in admin user account (or use bellow one)
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 SeAT Admin Login URL Generator
+2023-06-02 09:49:33 Checking if 'admin' is a super user
+2023-06-02 09:49:33 Generating authentication token
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 Your authentication URL is valid for 60 seconds.
+2023-06-02 09:49:33 https://seat.domain.tld/auth/login/admin/aDvMAcd7GQPXFfhS3aIH9dh4opwcvASB
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 
+2023-06-02 09:49:33 AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.19.0.4. Set the 'ServerName' directive globally to suppress this message
+2023-06-02 09:49:33 AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.19.0.4. Set the 'ServerName' directive globally to suppress this message
+2023-06-02 09:49:33 [Fri Jun 02 07:49:33.524019 2023] [mpm_prefork:notice] [pid 1] AH00163: Apache/2.4.56 (Debian) PHP/8.2.6 configured -- resuming normal operations
+2023-06-02 09:49:33 [Fri Jun 02 07:49:33.524084 2023] [core:notice] [pid 1] AH00094: Command line: 'apache2 -D FOREGROUND'
+
+

Try to authenticate yourself and verify everything is working well. If you don't find any issue, you can now restart the stack in daemon mode 🎉.

+

Use Ctrl+C in order to kill the stack and restart it in background:

+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up
+
+
+
+
docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up
+
+
+
+
+

Docker changes since SeAT 4

+

There have been a few minor changes to the docker-compose.yml file. Most notably, the containers have been renamed to disclose their purpose easier, we have moved from Dockerhub to GitHub Container Registry, and the stack now has a persistent storage volume.

+

If you customized your docker stack deployment, it is recommended that you take a look at the new docker-compose.yml file yourselves to see what exactly changed. +Last but not least, try to avoid tuning standard files as must as possible and use override syntax instead with a docker-compose.override.yml file (see official documentation).

+

Preperation

+

Before you upgrade, you need to backup.

+

Backup your database

+

The single most important thing you need is a backup of your SeAT 4 database. Without a backup you will not be able to recover in case of a disaster. So, head on over to the docker db backup section and do that right now.

+

Backup your env file

+

The .env file is the one that has your SeAT installations' configuration. It contains things like your SSO Client ID and Secret (aka: credentials). By default, SeAT docker installations live in /opt/seat-docker meaning your .env file will be at /opt/seat-docker/.env. Make a copy of this file and store it somewhere safe.

+

Stop SeAT 4

+

First, we need to stop the SeAT 4 stack. Assuming you have the default /opt/seat-docker location for your installation, cd to it first and then run:

+
docker compose down
+
+

The output should be similar to this:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
root@seat:/opt/seat-docker# docker compose down
+Stopping seat-web   ... done
+Stopping seat-cron    ... done
+Stopping seat-worker  ... done
+Removing seat-traefik     ... done
+Stopping seat-mariadb ... done
+Stopping seat-redis   ... done
+Removing seat-web   ... done
+Removing seat-cron    ... done
+Removing seat-worker  ... done
+Removing seat-traefik     ... done
+Removing seat-mariadb ... done
+Removing seat-redis   ... done
+Removing network seat-docker_seat-network
+
+

Upgrading to SeAT 5

+

Get the new docker-compose files

+
+

Warning

+

If you have made customisations to how you deployed SeAT with docker-compose, then you should probably not

+
+

be replacing the compose file like we are about to do. Instead, have a look at the new one here and adapt.

+

Next, we will download the new SeAT 5 docker-compose files. Do that with:

+
1
+2
+3
+4
+5
mv docker-compose.yml docker-compose.yml.seat4.bak
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.yml -o docker-compose.yml
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.mariadb.yml -o docker-compose.mariadb.yml
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.traefik.yml -o docker-compose.traefik.yml
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/docker-compose.proxy.yml -o docker-compose.proxy.yml
+
+

With this we have created a copy of the older docker-compose file (just in case), and downloaded the new one.

+

Update the .env file

+

This is one of the more important steps. The database configuration needs to be updated.

+

The easier is probably to download the new template and adapt variables according to your previous configuration as +some of them have been removed, newest appeared and overall have been reordered.

+
1
+2
mv .env .env.seat4.bak
+curl -L https://raw.githubusercontent.com/eveseat/seat-docker/master/.env -o .env
+
+

You can refer at any time to the online version of .env file on GitHub +The table bellow is provided as a variable mapping between SeAT 4.x and SeAT 5.x. You can use it as a reference.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SeAT 4.xSeAT 5.x
TRAEFIK_DOMAIN=seat.localSEAT_DOMAIN=seat.seat.local
SEAT_SUBDOMAIN=seatSEAT_DOMAIN=seat.seat.local
REDIS_HOST=redisREDIS_HOST=cache
PROXY_BACKEND_HTTP_PORT=8080
LOG_LEVEL=error
+

Bringing SeAT 5 up

+

The only thing that is left to do is to start the stack up again. The first time we are going to start SeAT 5 we won't use the -d flag. This is just so that you can see what's happening during the upgrade procedure. So, start SeAT with:

+
+
+
+

In case you want to use Traefik front of SeAT ui container, you'll need to setup the following environment variable: TRAEFIK_ACME_EMAIL. +You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up

+
+
+

In case you want to use a custom reverse proxy front of SeAT ui container, you'll need to setup the new environment variable PROXY_BACKEND_HTTP_PORT. +You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up

+
+
+
+

You should first see some download progress bars downloading the new SeAT version.

+

After a while, seat should start up similar to this:

+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
...
+
+seat_local-front-1  | mysqld is alive
+seat_local-front-1  | PONG
+seat_local-front-1  | starting web service
+seat_local-front-1  | Processing plugins from SEAT_PLUGINS
+seat_local-front-1  | Loading composer repositories with package information
+seat_local-front-1  | Info from https://repo.packagist.org: #StandWithUkraine
+seat_local-front-1  | Updating dependencies
+...
+
+
+

Warning

+

Do not interrupt SeAT during this phase. It will leave your database in a potentially corrupt state, meaning you are going to have to do some extra pluming to get a backup restored. Not a train smash, but not worth it.

+
+

Eventually, when everything is done you should start seeing the following output:

+
1
+2
+3
+4
seat_local-front-1  | AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.25.0.5. Set the 'ServerName' directive globally to suppress this message
+seat_local-front-1  | AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 172.25.0.5. Set the 'ServerName' directive globally to suppress this message
+seat_local-front-1  | [Sun May 21 21:10:46.869842 2023] [mpm_prefork:notice] [pid 1] AH00163: Apache/2.4.56 (Debian) PHP/8.1.19 configured -- resuming normal operations
+seat_local-front-1  | [Sun May 21 21:10:46.869944 2023] [core:notice] [pid 1] AH00094: Command line: 'apache2 -D FOREGROUND'
+
+

This is a good sign, and means everything is now ready!

+

Check your installation

+

The first obvious step will be to check that you can access the web UI. If not, something is probably weird with the web server configuration and needs some tweaking.

+

If everything seems to be working fine, you can hit ++crtl+c++ which will bring the stack down gracefully. This might take up to 30 seconds.

+
1
+2
+3
+4
+5
+6
^CGracefully stopping... (press Ctrl+C again to force)
+Stopping seat-docker_scheduler_1 ...
+Stopping seat-docker_worker_1    ...
+Stopping seat-docker_front_1     ...
+Stopping seat-docker_traefik_1   ... done
+Stopping seat-docker_cache_1     ...
+
+

Then, bring it back up with the -d flag.

+
+
+
+

In case you want to use Traefik front of SeAT ui container, you'll need to setup the following environment variable: TRAEFIK_ACME_EMAIL. +You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d

+
+
+

In case you want to use a custom reverse proxy front of SeAT ui container, you'll need to setup the new environment variable PROXY_BACKEND_HTTP_PORT. +You'll then use the following command to boot the stack docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d

+
+
+
+

Congrats, and welcome to SeAT 5!

+

Problems

+

Should you have any issue with the installation, please contact us on Discord.

+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/upgrading/general/index.html b/upgrading/general/index.html new file mode 100644 index 00000000..c47b3974 --- /dev/null +++ b/upgrading/general/index.html @@ -0,0 +1,1509 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + General - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

General Upgrades

+

As with anything, it is a very good idea to have backups ready before attempting any upgrades. +In the case of SeAT, the most important component needs to be backed up is the SeAT database. +Should something go wrong, then you can simply re-install SeAT, restore the database, and you should be good to go.

+

Docker installation

+

As expected, updates for SeAT are deployed via images on the GitHub Container Registry. +Every package version release will automatically start the build process to generate a new docker image. +This means updates are super simple in the docker world. To update your instance, simply run:

+
+
+
+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
# Update to the latest dockerhub images
+docker-compose pull
+
+# Take the stack down
+docker-compose down
+
+# Bring the stack back up
+docker-compose up -d
+
+# Cleanup any dangling images
+docker image prune -f
+
+
+
+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
# Update to the latest dockerhub images
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml pull
+
+# Take the stack down
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml down
+
+# Bring the stack back up
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.traefik.yml up -d
+
+# Cleanup any dangling images
+docker image prune -f
+
+
+
+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
# Update to the latest dockerhub images
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml pull
+
+# Take the stack down
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml down
+
+# Bring the stack back up
+docker compose -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.proxy.yml up -d
+
+# Cleanup any dangling images
+docker image prune -f
+
+
+
+
+
+

Better safe then sorry

+

Always perform a database backup of your database before doing an update. Always.

+
+

Blade installation

+
    +
  • Ensure that you are in the path where you installed. By default this should be /var/www/seat.
    • +
  • Cut jobs processing.
    • +
+
supervisorctl stop all
+
+
    +
  • Put your application into maintenance mode. This will ensure that no request from the outside will hit your applications logic, and also help you perform an upgrade uninterrupted. Do this with:
    • +
+
php artisan down
+
+
    +
  • Its a good thing to update composer itself. This is not a hard requirement, but definitely recommended. Do this with:
    • +
+
composer self-update
+
+
    +
  • The next thing to do is get the latest SeAT packages. The below example adds the --no-dev argument as these packages are generally not needed in production. Upgrade the packages with:
    • +
+
composer update --no-dev
+
+
    +
  • With the packages upgraded, we can now publish any new migrations/assets/configs. This can be done with:
    • +
+
php artisan vendor:publish --force --all
+
+
    +
  • Once the needed files are published, run any new/outstanding migrations with:
    • +
+
php artisan migrate
+
+
    +
  • With the migrations done, run the seeders to update any static data:
    • +
+
php artisan db:seed --class=Seat\\Console\\database\\seeds\\ScheduleSeeder
+
+
    +
  • Finally, we can simply bring our application back out of maintenance mode with:
    • +
+
php artisan up
+
+
    +
  • Prune job queue, this will prevent already queued jobs to use old codebase
    • +
+
php artisan cache:clear
+
+
    +
  • Renew cached configuration and routes
    • +
+
1
+2
php artisan config:cache
+php artisan route:cache
+
+
    +
  • Restart the supervisor workers to ensure they also pickup the latest code:
    • +
+
supervisorctl start all
+
+
+

Better safe then sorry

+

Always perform a database backup of your database before doing an update. Always.

+

You can use mysqldump -uroot -p seat > backup.sql (change root and seat according to your configuration)

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/user_guides/moons_reporter/index.html b/user_guides/moons_reporter/index.html new file mode 100644 index 00000000..98ed55ab --- /dev/null +++ b/user_guides/moons_reporter/index.html @@ -0,0 +1,1551 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Moons Reporter - SeAT Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + + +

SeAT

+

Moons Reporter

+

Introduced in SeAT 4.0, a new tool is available to assist you in your moon management task by leveraging your intelligence desk. +Like your old google/excel sheet, it will gather all your intel related to moon probing. +It provides a centralized and convenient way to store reports and search through them.

+

Of course, like other modules, you are able to restrict its usage using ACL by choosing who can view it and/or import reports.

+

Moons Reporter

+

Importing reports

+

Importing a report

+

Seeding an intelligence database is usually a really long task. The Moons Reporter simplifies the process as much as possible by accepting your raw moon report collected by the in-game moon probing interface.

+

Here is the process which need to be follow in order to be able to import a new moon report :

+
    +
  • fire your probe in-game and wait for the report to land
    • +
  • use the "Copy to Clipboard" button from your "Moon Probe and Analysis" window
    • +
  • go on the Moons Report and hit the "Import" button located on top right (1)
    • +
  • paste copied content in the opening modal and hit "Post report"
    • +
+

That's all, SeAT will take care of your report and apply change accordingly.

+
+

Tip

+

You can paste multiple moon report in once - so, to gain time and save clicks, you will probably prefer to scans all moons in a system before importing them into SeAT.

+
+
+

Info

+

When importing a report targeting an already imported moon report, existing data will be erased and replaced by the new report.

+
+
+

Caution

+

In case you have to import data from an existing sheet, you will have to generate report based on your information. +Please put an eye into migrate section from this documentation.

+
+ +

Search Engine

+

The Moons Reporter is shipped with an advanced search panel (2) which allow you to search moons by different criteria :

+
    +
  • region
    • +
  • constellation
    • +
  • system
    • +
  • rank
    • +
  • produces
    • +
+

Region, Constellation and System filters will be driven together depending on what you're doing - making your search easier.

+

You are able to provide multiple rank into the rank filter (like ubiquitous, common, uncommon, rare and exceptional). +When you are using this filter, only moon which contain all criteria will be displayed. +For example, if you are searching for a moon which contain common and uncommon materials, simply select both criteria.

+

Like rank filter, the produces filter is allowing you to track for moons containing multiple materials. +As an example, you can search for moons producing both Vanadium and Cobalt.

+

To make a search, once you put your criteria, use the search button.

+

Moon Information

+

Moon Metadata

+

Main pane (3) is showing you the list of all probed moons. You'll get quick intel on them with indicator and sovereignty columns. +However, in case you want more information regarding a moon, you can click on the eye button which will show you the moon card.

+

Displayed sovereignty depends on public in-game collected intel regarding systems. Those data are updated once a day - after down-time.

+

Moon Card

+

Moon Details

+

You are able to access details regarding a moon, simple by clicking on the eye button, located in the action column. +Moon card will give you some valuable information like contained raw materials, reprocessed materials and reactions candidates.

+

The Moons Reporter is not only showing you types but also figures like volume, quantity and estimated value. +All of them are computed based on a regular chunk of 20,000.00m3 - and upgraded to 30 days for convenience. +The base reprocessing yield is 80% - however, you are able to determine which yield must be used into your user profile.

+

Moon Stats

+

Some stats are provide in Moons Reporter footer (4). They are showing you the number of raw materials, per rank, from all your scanned moons. +Those stats are list in the same order as the indicator column :

+
    +
  • Gaz or Ubiquitous asteroids
    • +
  • R8 or Common asteroids
    • +
  • R16 or Uncommon asteroids
    • +
  • R32 or Rare asteroids
    • +
  • R64 or Exceptional asteroids
    • +
  • Ore (standard asteroids - like Scordite, Spodumain, etc...)
    • +
+

Migrating

+

Moons Reporter can only accept reports using Eve Online raw format. As a result, you will probably not be able to import data from an existing sheet without process. +Luckily, the used format is quite simple to recover from collected data. You will find bellow a sample :

+
1
+2
+3
+4
+5
+6
+7
Moon    Moon Product    Quantity    Ore TypeID  SolarSystemID   PlanetID    MoonID
+
+OP9L-F II - Moon 1
+    Glossy Scordite 0.300030559301  46687   30002173    40138526    40138527
+    Immaculate Jaspet   0.328855156898  46682   30002173    40138526    40138527
+    Pellucid Crokite    0.287893354893  46677   30002173    40138526    40138527
+    Sylvite 0.083220936358  45491   30002173    40138526    40138527
+
+

Keep the two first lines as it, it's the report header. +You will then have same format for every moon you need to put inside the report :

+
    +
  • The full qualified moon name
    • +
  • One line per moon compound - indented by a tabulation
    • +
+

Moon compound line are built using :

+
    +
  • Type name
    • +
  • Rate (number between 0 and 1, using . a decimal separator - without thousands separator)
    • +
  • Type identifier (number without either decimal or thousands separator)
    • +
  • Solar system identifier (number without either decimal or thousands separator)
    • +
  • Planet identifier (number without either decimal or thousands separator)
    • +
  • Moon identifier (number without either decimal or thousands separator)
    • +
+

If you need either the type name or the type identifier, you can use the amazing work from Fuzzy Steve :

+ +
+

Caution

+

Take care of separators. Report is using tabulations between column and not simple spaces. +Also, each line must end with an end line and a carriage return character (CRLF - or Windows carriage return format)

+
+ + + + + + + + +
+
+ + +
+ +
+ + + +
+
+
+
+ + + + + + + + + \ No newline at end of file