Deploying an application to an ALPON device using the Sixfab API is straightforward and powerful, especially with its real-time JSON streaming for deployment progress. In this blog post, I'll walk you through the process, sharing tips and examples along the way. Don't worry if you're new to APIs — I'll keep things simple and explain every step.

Prerequisites

Before diving in, here’s what you need to get started:

1. API Key: Log in to your Sixfab Connect account. Navigate to Developer > API Keys to create and copy your API key.
2. ALPON Device: Ensure you have a registered ALPON device under your account.
3. Asset Identifier: You’ll need the asset ID of your device, which can be any of the following:

You can find these details in the Assets tab of your Sixfab Connect account by clicking on the specific ALPON device.

The Endpoint

The API endpoint you’ll use for deploying an app is:

Replace {asset_id} with the appropriate identifier for your ALPON device (e.g., S/N, UUID). Don’t worry about being restricted to a specific identifier—use whichever is most convenient.

Making the Request

For this tutorial, I’ll demonstrate using curl to send the request, but feel free to use any HTTP client like Postman, Python’s requests, or JavaScript’s fetch.

Here’s an example payload for deploying an NGINX application:

{
  "name": "nginx-app",
  "image": "nginx:latest",
  "host_network": false,
  "privileged": false,
  "environments": [
    { "key": "ENV", "value": "production" }
  ],
  "ports": [
    { "host_port": 30001, "target_port": 80 }
  ],
}

Note: Make sure the host_port is within the valid range of 30000-32767 to avoid errors. You can also create a HTML page on your ALPON device’s alpon directory using a remote terminal. Then you can use volumes to see that page in action.

Example volume mounting:

"volumes": [
    {"local": "/home/alpon", "target": "/usr/share/nginx/html", "readonly": False}
]

Using curl, your request might look like this:

curl -X POST https://api.sixfab.com/v1/assets/{asset_id}/alpon/apps \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
  "name": "nginx-app",
  "image": "nginx:latest",
  "host_network": false,
  "privileged": false,
  "environments": [{ "key": "ENV", "value": "production" }],
  "ports": [
    { "host_port": 30001, "target_port": 80 }
  ]
}'

You'll see these messages as your app is being deployed.
For example, this message usually means that the device successfully pulled the image that we are trying to deploy:

At this step, the device has run the app and it's ready to go:

The API returns one more message with "status": "Success" to indicate that the deployment process successfully completed:

At this step, you can go to the {your_ip_address}:30001 to see the nginx running.

Tracking Deployment Progress

The API streams JSON events to keep you updated in real-time. You’ll see three types of status updates:

1. Running: The deployment is in progress.

2. Success: The deployment is complete.

3. Fail: The deployment failed.

If you’re using curl, you’ll see these updates in your terminal as they happen. Libraries like Python’s requests make it easy to stream and process responses.

Because the API responds with a text/event-stream content type, you must use the stream=True parameter when making the request. This ensures that the response can be processed incrementally as it arrives. Using response.iter_lines(), you can efficiently iterate through each line of the streamed response without loading everything into memory.

Here’s an example using Python:

import requests
import json

API_KEY = "your-api-key"
ASSET_ID = "your-asset-identifier"
URL = f"https://api.sixfab.com/v1/assets/{ASSET_ID}/alpon/apps"

payload = {
    "name": "nginx-app",
    "image": "nginx:latest",
    "host_network": False,
    "privileged": False,
    "environments": [{"key": "ENV", "value": "production"}],
    "ports": [{"host_port": 30500, "target_port": 80}],
}

headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

response = requests.post(URL, json=payload, headers=headers, stream=True)

for line in response.iter_lines():
    if line:
        data = line.decode("utf-8").strip()
        if data.startswith("data:"):
            data = data[5:].strip()  # Removes the "data: " prefix
            # at this point the data is a JSON string

        try:
            response_json = json.loads(data)
            print(response_json)

            # Act on the response
            if response_json.get("status") == "Running":
                print("Deployment is in progress. Monitor for updates...")
            elif response_json.get("status") == "Success":
                print(
                    "Deployment completed successfully! Check your app at http://{your_ip_address}:30500."
                )
            elif response_json.get("status") == "Fail":
                print(f"Deployment failed: {response_json.get('message')}")
        except json.JSONDecodeError:
            print(f"Failed to parse JSON: {data}")

At this point, we can tinker with the data that is streaming.

Also using a helper method to parse responses would make your code much cleaner and reusable. Here’s an example with a helper parser:

import requests
import json

API_KEY = "api-key"
ASSET_ID = "your-asset-id"
URL = f"https://api.sixfab.com/v1/assets/{ASSET_ID}/alpon/apps"

payload = {
    "name": "nginx-app",
    "image": "nginx:latest",
    "host_network": False,
    "privileged": False,
    "environments": [{"key": "ENV", "value": "production"}],
    "ports": [{"host_port": 30500, "target_port": 80}],
}

headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}


def sse_parser(response):
    """
    Parses an SSE stream response and yields JSON objects for each event.
    """
    for line in response.iter_lines():
        if line:
            data = line.decode("utf-8").strip()
            if data.startswith("data:"):
                data = data[5:].strip()  # Removes the 'data:' prefix

            try:
                yield json.loads(data)
            except json.JSONDecodeError:
                print(f"Failed to parse JSON: {data}")


response = requests.post(URL, json=payload, headers=headers, stream=True)

# Use the helper method to process the SSE stream
# Pass the streaming response to our parser:
for event in sse_parser(response):
    print(event) # You can examine the event here.

    # We can act on the response
    if event.get("status") == "Running":
        print("Deployment is in progress. Monitor for updates...")
    elif event.get("status") == "Success":
        print(
            "Deployment completed successfully! Check your app at http://your_ip_address:30532."
        )
    elif event.get("status") == "Fail":
        print(f"Deployment failed: {event.get('message')}")

You can try various things like saving the app's data to your database, sending an email notification, or even triggering another deployment.

Also you can handle the failed deployments with their corresponding codes for flawless interaction. You can see all of the possible error codes that this endpoint could return at Sixfab API Deploy App Documentation.

Ideas for Tinkering with Response Data

You can use the response data to trigger various actions or provide user feedback:

1. Real-Time Notifications:

If you’re building a web interface, you can update the UI with progress messages, such as showing a spinner during deployment.

2. Automated Error Handling:

• Log or retry failed deployments if the status is Fail.
• Display specific error messages to help users troubleshoot quickly.

3. Post-Deployment Automation:

Once the deployment is successful (status: Success), redirect users to the running app or perform further configurations automatically.

4. Monitoring & Analytics:

Save deployment statuses to a database to analyze success rates or monitor deployment times.

5. Conditional Actions:

Trigger custom workflows based on specific deployment messages, such as running post-deployment scripts or sending a success notification to your team.

Troubleshooting Common Errors

Here are a few errors you might encounter and how to resolve them:

1. Port Range Error:

• Message: Port is not in the correct range. The range of valid ports is 30000-32767.
• Solution: Adjust the host_port in your request payload to fit within the valid range.

2. Device Not Reachable:

• Message: Device not reachable
• Solution: Ensure your ALPON device is online and properly connected.

3. Asset Not Found:

• Message: Asset not found
• Solution: Verify that you’re using the correct asset ID (S/N, SIM SID, ICCID, or UUID).

4. Port In Use Error:

• Message: The desired port is already in use.
• Solution: Adjust the host_port in your request payload to use a port that is not in use.

Wrapping Up

Deploying apps to ALPON devices with the Sixfab API is seamless once you understand the process. By following the steps outlined above, you’ll have your applications running in no time. Whether you’re building IoT solutions or deploying custom apps, Sixfab’s powerful tools and real-time feedback make the process intuitive and developer-friendly.