aa-wanderer-map

aa-wanderer-map

An Alliance Auth plugin that integrates your Alliance Auth installation with Wanderer wormhole mapping service, providing automated access control list (ACL) management.

This is a maintained fork of the original aa-wanderer by T'rahk Rokym, featuring bug fixes, improvements, and ongoing maintenance.

Features

• Automated access control list (ACL) management for Wanderer maps
• Granular permission system based on Alliance Auth states, groups, characters, corporations, alliances, and factions
• Automatic synchronization of user characters with Wanderer map access
• Support for multiple Wanderer instances and maps
• Periodic cleanup tasks to maintain ACL integrity
• Preserves admin and manager roles on the managed ACL

Recent Updates

v0.1.6 - Enhanced ACL management to allow usage of existing ACL, and control of admin/manager

v0.1.5 - Fixed migration errors and improved database table initialization handling

Credits

• T'rahk Rokym - Original aa-wanderer implementation
• A-A-Ron - allianceauth-multiverse architecture that enabled multiple service support

How It Works

aa-wanderer-map creates and manages a dedicated access list on your Wanderer map, separate from any manually configured access lists. This managed ACL is automatically synchronized with your Alliance Auth permissions.

Notes:

• The managed ACL created by aa-wanderer-map should not be manually edited
• Users who lose Alliance Auth permissions will be automatically removed from the managed ACL, regardless of their role

Installation

Step 1 - Check Prerequisites

1. Alliance Auth Installation - This plugin requires a working Alliance Auth installation. If you haven't installed Alliance Auth yet, please follow the official Alliance Auth installation guide.
2. Wanderer Map Administrator Access - You must have administrator access to a Wanderer map to obtain the map API key required for creating the managed access list.

Step 2 - Install Application

Ensure you are in the virtual environment of your Alliance Auth installation, then install the latest release from PyPI:

pip install aa-wanderer-map

Step 3 - Configure Settings

Add the following configuration to your Alliance Auth settings file (local.py):

1. Add 'wanderer' to INSTALLED_APPS:

INSTALLED_APPS += [
    'wanderer',
]

2. Configure the periodic cleanup task:

CELERYBEAT_SCHEDULE['wanderer_cleanup_access_lists'] = {
    'task': 'wanderer.tasks.cleanup_all_access_lists',
    'schedule': crontab(minute='0', hour='*/1'),
}

Step 4 - Finalize Installation

Run migrations and collect static files:

python manage.py migrate
python manage.py collectstatic --noinput

Restart your Alliance Auth supervisor services:

supervisorctl restart myauth:

Management Commands

The following Django management commands are available:

Usage Examples:

Sync all maps:

python manage.py wanderer_cleanup_acls

Sync a specific map:

python manage.py wanderer_cleanup_acls --map-id 5

The command queues Celery tasks for role synchronization. Check your logs to see the progress and results.

Usage

Creating a Wanderer Map

When creating a new Wanderer-managed map in Django Admin:

1. Navigate to Django Admin → Wanderer → Wanderer Managed Maps → Add
2. Fill in the map details:
   • Name: A descriptive name for the map
   • Wanderer URL: The base URL of your Wanderer instance (e.g., https://wanderer.ltd)
   • Map slug: The unique identifier for the map in Wanderer
   • Map API key: The API key for the map (with admin permissions)
3. In the Access List Selection section:
   • Create new ACL: Alliance Auth creates a fresh ACL for this map (recommended)
   • Use existing: Select from existing ACLs already on the map in Wanderer
4. Configure Member Access permissions:
   • Choose which states, groups, characters, corporations, alliances, or factions can access the map
   • Users matching these criteria will be able to link their account and access the map as members
5. Save the map

Important Notes:

• If you select an existing ACL, Alliance Auth will manage it going forward. Manual changes to the ACL may be overwritten during cleanup.
• Each map creates a dynamic service in Alliance Auth that users can link to

Assigning Map Admins and Managers

To automatically assign users or groups as map admins or managers:

1. Navigate to Django Admin → Wanderer → Wanderer Managed Maps
2. Select and edit the map you want to configure
3. In the Admin Roles section:
   • Admin users: Add individual users who should have admin role on the map
   • Admin groups: Add groups whose members should have admin role on the map
4. In the Manager Roles section:
   • Manager users: Add individual users who should have manager role on the map
   • Manager groups: Add groups whose members should have manager role on the map
5. Save the map
6. Role synchronization happens automatically:
   • Immediately: Changes trigger automatic sync via signal handlers
   • Hourly: Periodic cleanup task ensures consistency
   • Manual sync options:
     • Use the "Sync ACL roles now" action in the Django admin (select maps → Actions dropdown)
     • Or run: python manage.py wanderer_cleanup_acls
     • Or sync specific map: python manage.py wanderer_cleanup_acls --map-id 5

Important Notes:

• All characters (main + alts) for each assigned user receive the admin/manager role, not just their main character
• Role priority: ADMIN > MANAGER > MEMBER (if a user is in multiple categories, they get the highest role)
• Manually-set admin/manager roles (not managed by Auth) are preserved during cleanup, as long as the character is authorized to access the map
• Users must still have access permissions (configured in Member Access) to be on the ACL

---

Contributing

Development Setup

To contribute to this project or test it locally, follow these steps:

1. Install System Dependencies

Before setting up the development environment, you need to install system-level dependencies required by Alliance Auth:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y pkg-config python3-dev default-libmysqlclient-dev build-essential git redis-server

Or for MariaDB:

sudo apt-get install -y pkg-config python3-dev libmariadb-dev build-essential git redis-server

Fedora/RHEL/CentOS:

sudo dnf install -y pkg-config python3-devel mysql-devel gcc git redis

macOS:

brew install pkg-config mysql redis git

2. Clone the Repository

git clone https://github.com/guarzo/aa-wanderer-map.git
cd aa-wanderer-map

3. Create Virtual Environment

Using the setup script (recommended):

# Make the script executable
chmod +x dev-setup.sh

# Run the setup script
./dev-setup.sh

Manual setup:

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Linux/Mac
# or
venv\Scripts\activate  # On Windows

# Upgrade pip
pip install --upgrade pip

# Install development dependencies
pip install -e .
pip install tox black isort flake8

4. Running Tests

# Activate venv if not already activated
source venv/bin/activate

# Run all tests with tox
tox

# Run specific Python version tests
tox -e py310-django42

# Check code formatting
black --check .

# Format code
black .

# Check import sorting
isort . --check-only

# Sort imports
isort .

# Run linter
flake8 wanderer/

# Run pylint
tox -e pylint

5. Building the Package

# Install build tools
pip install build

# Build the package
python -m build

# Check the built package
ls -la dist/

Contribution Guidelines

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Format your code: black . && isort .
5. Run the test suite: tox
6. Commit your changes with a descriptive message
7. Push to your branch: git push origin feature/your-feature-name
8. Open a Pull Request with a clear description of your changes

Troubleshooting

mysqlclient Build Errors

If you encounter errors like Can not find valid pkg-config name or mysql_config not found:

Solution: Install the required system packages:

# Ubuntu/Debian
sudo apt-get install pkg-config python3-dev default-libmysqlclient-dev build-essential

# Fedora/RHEL/CentOS
sudo dnf install pkg-config python3-devel mysql-devel gcc

# macOS
brew install pkg-config mysql

Then retry the setup.

Redis Connection Errors

If tests fail with Redis connection errors:

# Start Redis
redis-server --daemonize yes

# Or on macOS with Homebrew
brew services start redis

Code Formatting Issues

To format your code properly:

# Auto-format with Black
black .

# Sort imports
isort .

# Check for issues
flake8 wanderer/

# Then commit the changes
git add .
git commit -m "Fix formatting"

Support

Reporting Issues

Please report issues on the GitHub issue tracker.

When reporting an issue, please include:

• Steps to reproduce the issue
• Expected behavior
• Actual behavior
• Python version
• Alliance Auth version
• Relevant error messages or logs
• Operating system and version

Getting Help

For questions and support:

• Open an issue on GitHub with the question label
• Check existing issues for similar questions or problems

License

This project is licensed under the MIT License. See the LICENSE file for details.