README

A very simple and thin API client for the Fly.io machine API.

Installation

You can install the package via composer:

composer require securitydiscovery/laravel-fly-machines

You can publish the config file with:

php artisan vendor:publish --tag="fly-machines-config"

This is the contents of the published config file:

// config for SecurityDiscovery/LaravelFlyMachines
return [
    'proto' => env('FLY_API_PROTO', 'http'),
    // The endpoint to the Fly machines API.
    'endpoint' => env('FLY_API_HOSTNAME', '127.0.0.1:4280'),
    // The token to authenticate to the API.
    'token' => env('FLY_API_TOKEN'),
];

Usage

use SecurityDiscovery\LaravelFlyMachines\Facades\LaravelFlyMachines as FlyMachines;

List machines of a Fly.io App:

FlyMachines::machines('my-fly-app')->list()

Launch a machine.

FlyMachines::machines('my-fly-app')->launch(machine: $config)

Update a machine.

FlyMachines::machines('my-fly-app')->update(machineId: "machineId", machine: $config, nonce: "nonce")

Get a machine.

FlyMachines::machines('my-fly-app')->get(machineId: "machineId")

Stop a machine.

FlyMachines::machines('my-fly-app')->stop(machineId: "machineId")

Start a machine.

FlyMachines::machines('my-fly-app')->start(machineId: "machineId")

Send a signal to a machine.

FlyMachines::machines('my-fly-app')->signal(machineId: "machineId", signal: 9)

Kill a machine (uses the signal 9 (SIGKILL), the same as the above call).

FlyMachines::machines('my-fly-app')->kill(machineId: "machineId")

Restart a machine.

FlyMachines::machines('my-fly-app')->restart(machineId: "machineId", forceStop: true, timeout: 10, signal: 9)

Find a lease for a machine.

FlyMachines::machines('my-fly-app')->findLease(machineId: "machineId")

Acquire a lease for a machine.

FlyMachines::machines('my-fly-app')->acquireLease(machineId: "machineId", ttl: 30)

Release a lease of a machine.

FlyMachines::machines('my-fly-app')->releaseLease(machineId: "machineId", nonce: "nonce")

Wait for a machine.

FlyMachines::machines('my-fly-app')->releaseLease(machineId: "machineId", instanceId: "instanceId", state: "started", timeout: 30)

Destroy a machine.

FlyMachines::machines('my-fly-app')->destroy(machineId: "machineId", kill: true)

Launch a Fly.io machine

use SecurityDiscovery\LaravelFlyMachines\Facades\LaravelFlyMachines as FlyMachines;
use SecurityDiscovery\LaravelFlyMachines\Helpers\Machine;

$machineConfig = Machine();
$machine = FlyMachines::machines('my-fly-app')
    ->launch(
        Machine::builder()
            ->image(image: 'registry-1.docker.io/flyio/postgres:14.4')
            ->toArray()
    );

Launch a Fly.io machine without the helper

use SecurityDiscovery\LaravelFlyMachines\Facades\LaravelFlyMachines as FlyMachines;

$machine = FlyMachines::machines('my-fly-app')->launch([
    'config' => [
        'image' => 'registry-1.docker.io/flyio/postgres:14.4',
    ],
    'region' => 'fra',
]);

Fly Machine Helper

use SecurityDiscovery\LaravelFlyMachines\Facades\LaravelFlyMachines as FlyMachines;
use SecurityDiscovery\LaravelFlyMachines\Helpers\Machine;

$machineConfig = Machine::builder()
    ->image(image: 'my.registry.io/a/b:14.4')  // Required
    ->init(                                    // Optional
        entrypoint: ['/bin/sh'],
        exec: ['exec'],
        cmd: ['cmd'],
        tty: false
    )
    ->retries(                                 // Optional
        max_retries: 3, 
        policy: 'on-failure'
    )
    ->mount(                                   // Optional
        volume_id: 'vol_123',
        path: '/data'
    )
    
    ->env(name: 'NAME_1', value: 'VALUE_1')    // Optional
    ->env(name: 'NAME_2', value: 'VALUE_2')    // Optional
    
    ->auto_destroy(auto_destroy: True)         // Optional
    ->name(name: 'my_machine')                 // Optional
    ->schedule(schedule: 'daily')              // Optional
    ->region(region: 'fra')                    // Optional
    ->size(size: 'shared-cpu-1x' )             // Optional | WARNING: Use 'guest' or 'size'
    ->guest(                                   // Optional
        cpus: 1,
        memory_mb: 2*256,
        cpu_kind: 'shared',
        kernel_args: []
    )
    ->process()                                // TODO: Document this
    ->toArray();

See more here https://fly.io/docs/machines/working-with-machines/.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Sebastien Kaul
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

"Laravel" is a registered trademark of Taylor Otwell. This project is not affiliated, associated, endorsed, or sponsored by Taylor Otwell, nor has it been reviewed, tested, or certified by Taylor Otwell. The use of the trademark "Laravel" is for informational and descriptive purposes only. Laravel Workflow is not officially related to the Laravel trademark or Taylor Otwell.