Location Management

Organizing nodes by geographic or logical locations

Locations help organize your nodes geographically or logically. They serve as a way to group nodes and provide a cleaner deployment interface for administrators and users.

What are Locations?

Locations are simple organizational units that group nodes together. They’re commonly used to represent:

• Geographic Locations: US-East, EU-West, Asia-Pacific
• Data Centers: NYC1, LON1, SFO2
• Providers: AWS, DigitalOcean, OVH
• Logical Groups: Production, Development, Testing

Location Model

Locations are simple models with minimal fields (from app/Models/Location.php:42-45):

public static array $validationRules = [
    'short' => 'required|string|between:1,60|unique:locations,short',
    'long' => 'string|nullable|between:1,191',
];

Fields

• short: A short identifier (e.g., “us-east”, “eu-1”)
  • Required
  • 1-60 characters
  • Must be unique
• long: A descriptive name (e.g., “United States - East Coast”)
  • Optional
  • Up to 191 characters

Creating a Location

1. Navigate to Locations

   Go to Admin Panel → Locations

2. Fill in Details

   Location Information

   • Short Code: A unique identifier (e.g., us-east)
   • Description: Full descriptive name (e.g., United States - East Coast)
3. Create Location

   Click Create to save the location

Locations must be created before you can add nodes. Each node must be assigned to a location.

Viewing Locations

The locations index page displays:

• Short code
• Long description
• Number of nodes in the location
• Number of servers in the location

From app/Http/Controllers/Admin/LocationController.php:36-40:

public function index(): View
{
    return view('admin.locations.index', [
        'locations' => $this->repository->getAllWithDetails(),
    ]);
}

Location Details

Clicking on a location shows:

• All nodes assigned to this location
• Node statistics (servers, memory, disk)
• Total resources across all nodes
• Ability to edit or delete the location

Updating a Location

1. Navigate to Location

   Click on the location you want to edit

2. Modify Details

   Update the short code or description

3. Save Changes

   Click Update to save your changes

From app/Http/Controllers/Admin/LocationController.php:73-82:

public function update(LocationFormRequest $request, Location $location): RedirectResponse
{
    if ($request->input('action') === 'delete') {
        return $this->delete($location);
    }

    $this->updateService->handle($location->id, $request->normalize());
    $this->alert->success('Location was updated successfully.')->flash();

    return redirect()->route('admin.locations.view', $location->id);
}

Deleting a Location

You cannot delete a location that has nodes assigned to it. You must first delete or reassign all nodes.

To delete a location:

1. Remove All Nodes

   Ensure no nodes are assigned to this location

   • Delete nodes, or
   • Reassign nodes to a different location
2. Delete Location

   Navigate to the location and click Delete

3. Confirm Deletion

   Confirm you want to delete the location

From app/Http/Controllers/Admin/LocationController.php:91-102:

public function delete(Location $location): RedirectResponse
{
    try {
        $this->deletionService->handle($location->id);

        return redirect()->route('admin.locations');
    } catch (DisplayException $ex) {
        $this->alert->danger($ex->getMessage())->flash();
    }

    return redirect()->route('admin.locations.view', $location->id);
}

Location Relationships

Nodes

A location has many nodes (from app/Models/Location.php:57-60):

public function nodes(): HasMany
{
    return $this->hasMany(Node::class);
}

Servers

A location has many servers through nodes (from app/Models/Location.php:67-70):

public function servers(): HasManyThrough
{
    return $this->hasManyThrough(Server::class, Node::class);
}

This allows you to query all servers in a location, even though servers are directly assigned to nodes.

Use Cases

Geographic Distribution

Organize nodes by geographic regions for latency optimization:

Locations:
- us-west (United States - West Coast)
- us-east (United States - East Coast)
- eu-central (Europe - Central)
- asia-pacific (Asia - Pacific)

Users can then choose locations closest to them.

Data Center Organization

Group nodes by data center:

Locations:
- nyc1 (New York City - Data Center 1)
- lon1 (London - Data Center 1)
- fra1 (Frankfurt - Data Center 1)

Provider Separation

Separate nodes by hosting provider:

Locations:
- aws-us-east (Amazon Web Services - US East)
- do-nyc (DigitalOcean - New York)
- ovh-eu (OVH - Europe)

Environment Separation

Separate production from development:

Locations:
- prod (Production Servers)
- dev (Development Servers)
- staging (Staging Environment)

Server Creation Workflow

Locations affect server creation:

1. User/admin selects a Location
2. System filters available Nodes by location
3. User/admin selects a specific Node (or auto-deploy)
4. Server is created on the selected node

From app/Http/Controllers/Admin/Servers/CreateServerController.php:55-58:

return view('admin.servers.new', [
    'locations' => Location::all(),
    'nests' => $nests,
]);

Auto-Deployment

When using auto-deployment:

1. Select a location
2. Don’t select a specific node
3. System finds the best node in that location
4. Based on available resources

API Access

Locations are accessible via the API:

GET /api/application/locations

Returns all locations with their nodes and servers.

Best Practices

1. Consistent Naming: Use a consistent naming scheme

   • Good: us-east, us-west, eu-central
   • Bad: location1, loc-2, new-location

2. Descriptive Long Names: Make descriptions clear

   • Good: “United States - East Coast”
   • Bad: “US East”

3. Plan Ahead: Design your location structure before adding nodes

4. Logical Grouping: Group nodes by factors that matter to your users

   • Geographic proximity
   • Network performance
   • Provider reliability

5. Don’t Over-Organize: Too many locations can be confusing

   • Start with 3-5 locations
   • Expand as needed

Common Naming Schemes

Geographic

Short: us-east
Long: United States - East Coast

Short: eu-west
Long: Europe - Western Europe

Short: asia-se
Long: Asia - Southeast Asia

Data Center

Short: nyc1
Long: New York City - Data Center 1

Short: ams1
Long: Amsterdam - Data Center 1

Short: sgp1
Long: Singapore - Data Center 1

Provider-Based

Short: aws-east
Long: Amazon Web Services - US East

Short: do-nyc
Long: DigitalOcean - New York

Short: gcp-us
Long: Google Cloud Platform - US

Troubleshooting

Cannot Delete Location

Problem: Error when trying to delete a location

Solution: The location has nodes assigned to it. Either:

1. Delete all nodes in the location, or
2. Reassign nodes to a different location

Location Not Showing in Dropdown

Problem: Location doesn’t appear when creating servers

Solution: Ensure:

1. Location was created successfully
2. At least one node is assigned to the location
3. Node has available allocations

Short Code Conflict

Problem: “Short code already exists” error

Solution: Each location must have a unique short code. Choose a different identifier.

Migration Considerations

If you need to reorganize locations:

1. Create New Locations: Set up your new location structure
2. Reassign Nodes: Move nodes to new locations one by one
3. Delete Old Locations: Remove old locations after all nodes are moved

Changing a node’s location doesn’t affect existing servers, but may impact user expectations about geographic placement.

Next Steps

Node Management

Add nodes to your locations

Server Deployment

Deploy servers to your organized nodes