Operations Manual

Installation

Step 0 - Prerequisites

Structures is a plugin for Alliance Auth. If you don’t have Alliance Auth running already, please install it first before proceeding. (see the official AA installation guide for details)
Structures needs the app django-eveuniverse to function. Please make sure it is installed, before before installing the app.

Step 1 - Install app

Make sure you are in the virtual environment (venv) of your Alliance Auth installation. Then install the newest release from PyPI:

pip install aa-structures

Step 2 - Update Eve Online app

Update the Eve Online app used for authentication in your AA installation to include the following scopes:

esi-assets.read_corporation_assets.v1
esi-characters.read_notifications.v1
esi-corporations.read_starbases.v1
esi-corporations.read_structures.v1
esi-planets.read_customs_offices.v1
esi-universe.read_structures.v1

Step 3 - Configure AA settings

Configure your AA settings (local.py) as follows:

Add 'structures' to INSTALLED_APPS
Add below lines to your settings file:

CELERYBEAT_SCHEDULE['structures_update_all_structures'] = {
    'task': 'structures.tasks.update_all_structures',
    'schedule': crontab(minute='*/30'),
}
CELERYBEAT_SCHEDULE['structures_fetch_all_notifications'] = {
    'task': 'structures.tasks.fetch_all_notifications',
    'schedule': crontab(minute='*/5'),
}

Optional: Add additional settings if you want to change any defaults. See Settings for the full list.

Step 4 - Celery worker configuration

This app uses celery for critical functions like refreshing data from ESI. We strongly recommend to configure celery for high performance operations.

Please see this guide for details: Configuring celery workers

Step 5 - Finalize installation into AA

Run migrations & copy static files

python manage.py migrate
python manage.py collectstatic

Restart your supervisor services for AA

Step 6 - Preload Eve Universe data

In order to see structure fits you need to preload some data from ESI once. If you already have run those commands previously you can skip this step.

Load Eve Online structure types

python manage.py structures_load_eve

Step 7 - Setup permissions

Now you can setup permissions in Alliance Auth for your users.

See section Permissions below for details.

Step 8 - Setup notifications to Discord

The setup and configuration for Discord webhooks is done on the admin page under Structures.

To setup notifications you first need to add the Discord webhook that point to the channel you want notifications to appear to Webhooks. We would recommend that you also enable is_default for your main webhook, so that newly added structure owners automatically use this webhook. Alternatively you need to manually assign webhooks to existing owners after they have been added (see below).

Finally to verify that your webhook is correctly setup you can send a test notification. This is one of the available actions on Webhooks page.

Step 9 - Add structure owners

Next you need to add your first structure owner with the character that will be used for fetching structures. Just open the Structures app and click on “Add Structure Owner”. Note that only users with the appropriate permission will be able to see and use this function and that the character needs to be a director.

Once a structure owner is set the app will start fetching the corporation structures and related notifications. Wait a minute and then reload the structure list page to see the result.

You will need to add every corporation as Structure Owner to include their structures and notifications in the app.

Hint

As admin you can review all structures and notifications on the admin panel.

Updating

To update your existing installation of Structures first enable your virtual environment.

Then run the following commands from your AA project directory (the one that contains manage.py).

pip install -U aa-structures

python manage.py migrate

python manage.py collectstatic

Finally restart your AA supervisor services.

Settings

Here is a list of available settings for this app. They can be configured by adding them to your AA settings file (local.py).

Note

All settings are optional and the app will use the documented default settings if they are not used.

Settings for Structures.

STRUCTURES_ADD_TIMERS = True

Whether to automatically add timers for certain notifications on the timerboard (will have no effect if aa-timerboard app is not installed).

Will create timers from anchoring, lost shield and lost armor notifications.

STRUCTURES_ADMIN_NOTIFICATIONS_ENABLED = True: Whether admins will get notifications about import events like when someone adds a structure owner and when services for an owner are down.

STRUCTURES_DEFAULT_LANGUAGE = 'en': Sets the default language to be used in case no language can be determined e.g. this language will be used when creating timers Please use the language codes as defined in the base.py settings file.

STRUCTURES_DEFAULT_PAGE_LENGTH = 10: Default page size for structure list. Must be an integer value from the current options as seen in the app.

STRUCTURES_DEFAULT_TAGS_FILTER_ENABLED = False: Whether the structure list has default tags filter enabled by default.

STRUCTURES_ESI_DIRECTOR_ERROR_MAX_RETRIES = 3: Max retries before a character is deleted when ESI claims the character is not a director (Since this sometimes is reported wrongly by ESI).

STRUCTURES_ESI_TIMEOUT_ENABLED = True: Whether ESI timeout is enabled.

STRUCTURES_FEATURE_CUSTOMS_OFFICES = True: Enable / disable custom offices feature.

STRUCTURES_FEATURE_REFUELED_NOTIFICATIONS = True: Enable / disable refueled notifications feature.

STRUCTURES_FEATURE_STARBASES = True: Enable / disable starbases feature.

STRUCTURES_HOURS_UNTIL_STALE_NOTIFICATION = 24: Defines after how many hours a notification becomes stale. Stale notification will no longer be sent automatically.

STRUCTURES_MOON_EXTRACTION_TIMERS_ENABLED = True: Whether to create / remove timers from moon extraction notifications.

STRUCTURES_NOTIFICATION_DISABLE_ESI_FUEL_ALERTS = False: This allows you to turn off ESI fuel alert notifications to use the Structure’s generated fuel notifications exclusively.

STRUCTURES_NOTIFICATION_MAX_RETRIES = 3: Max number of retries for sending a notification if an error occurred e.g. rate limiting.

STRUCTURES_NOTIFICATION_SET_AVATAR = True: Wether structures sets the name and avatar icon of a webhook. When False the webhook will use it’s own values as set on the platform.

STRUCTURES_NOTIFICATION_SHOW_MOON_ORE = True: Wether ore details are shown on moon timers.

STRUCTURES_NOTIFICATION_SYNC_GRACE_MINUTES = 40: Max time in minutes since last successful notification sync before service is reported as down.

STRUCTURES_NOTIFICATION_WAIT_SEC = 5: Default wait time in seconds before retrying to send a notification to Discord after an error occurred.

STRUCTURES_PAGING_ENABLED = True: Whether paging is enabled for the structure list

STRUCTURES_REPORT_NPC_ATTACKS = True: Enable / disable sending notifications for attacks by NPCs (structure reinforcements are still reported).

STRUCTURES_SHOW_FUEL_EXPIRES_RELATIVE = True: Whether fuel expires in structures browser is shown as absolute value.

STRUCTURES_SHOW_JUMP_GATES = True: Whether to show the jump gates tab.

STRUCTURES_STRUCTURE_SYNC_GRACE_MINUTES = 120: Max time in minutes since last successful structures sync before service is reported as down.

STRUCTURES_TASKS_TIME_LIMIT = 7200: Hard timeout for tasks in seconds to reduce task accumulation during outages.

STRUCTURES_TIMERS_ARE_CORP_RESTRICTED = False: Whether created timers are corp restricted on the timerboard.

Permissions

This is an overview of all permissions used by this app. Note that all permissions are in the “general” section.

Name	Purpose	Code
Can access public views	User can access this app and view public pages, e.g. public POCO view	https://i.imgur.com/BK3MadZ.png
Can view corporation structures	User can see structures belonging to corporations of his characters only.	`general.view_corporation_structures`
Can view alliance structures	User can view all structures belonging to corporation in the alliance of the user.	`general.view_alliance_structures`
Can view all structures	User can see all structures in the system	`general.view_all_structures`
Can add new structure owner	User can add a corporation with it’s structures	`general.add_structure_owner`
Can view unanchoring timers for all structures the user can see	User can view unanchoring timers for all structures the user can see based on other permissions	`general.view_all_unanchoring_status`
Can view structure fittings	User can view structure fittings	`general.view_structure_fittings`

Admin tools

Admin site

Most admin tools are accessible on the admin site through actions. e.g. you can sent specific notifications or force a sync with the eve server for an owner.

See the respective actions list on the admin site for details.

Management commands

Some admin tools are available only as Django management command:

structures_load_eve: Preload static eve objects from ESI to speed up the app