Creating and Configuring Your First SZ Service in a Local Environment (No Infrastructure Required!)

Developing SZ services doesn’t necessitate complex infrastructure. Nearly all of the platform’s essential features can be replicated in your local development environment. This guide provides a clear walkthrough for creating and simulating services directly from your desktop IDE, allowing you to seamlessly generate, define, and test their behavior before deployment.

Step 1: Create a Virtual Environment

Before starting your SZ service development, it’s best practice to create a virtual environment. This isolates your project’s dependencies, preventing conflicts with packages from other projects.

You can create a virtual environment using a tool like virtualenv:

# Replace "my_fx_project" with your desired project name
virtualenv my_fx_project-env

Activate the virtual environment:

source my_fx_project-env/bin/activate

Step 2: Set Environment Variable

Set the EF_ENV environment variable to "local" to indicate you’re working in a local development environment:

export EF_ENV=local

Step 3: Project Directory Setup

Create a main project directory to house your services:

mkdir my_fx_project
cd my_fx_project

Step 4: Create Service Directory

Within your project directory, create a subdirectory for your specific service. The name should be alphanumeric, lowercase, and can include underscores (_) or hyphens (-), but no spaces:

mkdir my-service-name
cd my-service-name

Step 5: Create app.py

Inside your service directory, create an app.py file. This will be the entry point for your SZ service. Import the necessary context from the fx_ef core library:

# app.py
from fx_ef import context

# Your service code starts here

Step 6: Run app.py

Run the app.py file. This action generates two crucial JSON files for local simulation:

• ef_env.json: Simulates service parameters, secrets, and configurations.

• ef_package_state.json: Stores the service’s execution state.

Important: These files are solely for local simulation and are not used at runtime on the platform. They should not be committed to version control. A sample .gitignore for SZ projects is available [here](The GitIgnore File “The GitIgnore File”).

python app.py

Step 7: Expand Your Service

With the initial setup complete, you can now expand app.py with your actual service logic. Build and implement your SZ service within this file.

Step 8: Module Placement

Any additional Python modules your service relies on should be placed in the same directory as app.py. SZ does not support nested directories for modules.

Step 9: Create manifest.json

A manifest.json file is essential for describing your SZ service to the platform, enabling proper integration and communication. This file acts as a contract between your service and the platform, facilitating seamless integration.

Inside your service directory, create a manifest.json file. This JSON file will contain metadata about your service, allowing the SZ platform to understand and interact with it.

Understanding manifest.json: Defining Your Service

The manifest.json file plays a crucial role in describing your application to the DX Platform, as well as to fellow users and developers.

`manifest.json` Example:

{
  "description": "Service with manifest file",
  "entrypoint": "app.py",
  "execution_order": ["app_1.py", "app.py"],
  "tags": ["devops"],
  "trigger_events": ["ferris.apps.minio.file_uploaded"],
  "schedule": "54 * * * *",
  "allow_manual_triggering": true,
  "active": true,
  "output_events": ["test_type_101", "test_type_112"]
}

Parameters and Descriptions:

Step 10: Expand ef_env.json

The ef_env.json file is crucial for simulating your service’s environment during local development. While parameters, configurations, and secrets are managed differently on the SZ platform, you can define these elements within this JSON file for local simulation.

ef_env.json Example:

{
  "parameters": {
    "param1": "value1",
    "param2": "value2"
  },
  "secrets": {
    "secret_key1": "secret_value1",
    "secret_key2": "secret_value2"
  },
  "configs": {
    "config_key1": "config_value1",
    "config_key2": "config_value2"
  }
}

• `parameters`: Define parameters directly within this dictionary for local testing. These are typically accessed within your service code using the fx_ef library.

• `secrets`: Define sample secret values in this section for local simulation. On the platform, secrets are managed securely through the UI.

• `configs`: Specify configuration values in this dictionary. On the SZ platform, configuration values are usually managed through an external config.json file to keep sensitive data separate from your codebase.

Remember: The ef_env.json file is only for simulation purposes. On the SZ platform, parameters are passed through trigger event payloads, configurations come from the config.json file, and secrets are managed via the platform’s UI.

By expanding your ef_env.json file with appropriate parameters, secrets, and sample configuration values, you can effectively simulate your service’s behavior locally, allowing you to test and refine your service logic before deploying it to the SZ platform.

Step 12: Exploring the fx_ef Library

The fx_ef library acts as a bridge between your SZ service and the platform, enabling seamless integration of platform features into your service’s logic. It encapsulates essential functionalities for interacting with the SZ platform, including handling triggers, events, and more.

Leveraging fx_ef allows you to create robust and responsive SZ services that integrate smoothly with the platform’s ecosystem. Here’s a preview of its capabilities:

• Event Handling: Facilitates event-driven architecture, enabling your service to react to various platform triggers (e.g., incoming data events, external signals).

• Parameter Access: Provides methods to effortlessly access parameters passed through trigger event payloads on the SZ platform, allowing your service to make decisions based on provided inputs.

• Configuration Management: Simplifies accessing configuration values from within your service code, even though they are typically managed via a separate config.json file on the platform.

• Secrets Handling: Ensures your service can securely access secrets managed through the platform’s UI when running on the platform.

• Service State Tracking: Assists in managing your service’s execution state, tracking its progress and ensuring smooth operation.

By harnessing the capabilities of the fx_ef library, you can build powerful and versatile SZ services that seamlessly integrate with the SZ platform’s functionalities. The next section will delve deeper into specific ways to utilize these features in your service logic. Stay tuned as we explore the fx_ef library in depth, revealing the tools available for creating impactful and responsive SZ services.