Skip to content

Latest commit

 

History

History
257 lines (187 loc) · 7.97 KB

DEPLOYING.md

File metadata and controls

257 lines (187 loc) · 7.97 KB

Deploying

Deployment of pydomotic simply requires an environment that will execute code once per minute on your behalf. This lends itself well to strategies such as cron jobs and serverless platforms like AWS Lambda or Google Cloud Run.

Cron

On any unix system with cron support, open the crontab file with crontab -e and add the following line to install a new cron job to run pydomotic once per minute.

* * * * * python3 -m pydomotic --config-file /path/to/pydomotic.yml

Ensure that pydomotic is installed globally in this case.

Note that if you wish to load configuration from AWS S3 (in addition to installing any required dependencies for providers) you must run the following command. This is not required when deploying to AWS Lambda because the runtime already provides required dependencies.

$ pip install pydomotic[s3]

AWS Lambda

pydomotic is well suited for running on AWS Lambda and is the recommended deployment method for anyone looking for serious longterm reliability of their home automations with pydomotic.

Installation

This walk through will take you through the steps of deploying pydomotic to AWS Lambda using the Serverless Framework.

  1. Install Serverless Framework.

    $ npm install -g serverless

  2. Ensure you have AWS Credentials set up. This will involve configuring and setting the following environment variables.

    $ export AWS_ACCESS_KEY_ID=<your-key-here>
$ export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>

  3. Create a serverless.yml file with the following contents. Add any required environment variables as described in the providers documentation.

    # serverless.yml

service: pydomotic

provider:
  name: aws
  runtime: python3.9
  region: us-east-1  # replace as desired

package:
  patterns:
    - '!**'
    - 'pydomotic.yml'

plugins:
  - serverless-python-requirements

functions:
  cron:
    handler: pydomotic.lambda_handler.handler
    events:
      - schedule:
          rate: rate(1 minute)

  4. Create your pydomotic.yml file as descrbed in CONFIGURATION.md. Save it to the same directory as your serverless.yml file.

  5. The serverless-python-requirements plugin is used to manage and install dependencies.

    $ sls plugin install -n serverless-python-requirements

    This plugin will look for a requirements.txt file in the same directory as your serverless.yml file and deploy your lambda function along with all dependencies listed in this requirements file.

    Use Python Virtualenv to create this requirements file. This will create a virtual environment in the env directory and install pydomotic to it.

    $ pip install virtualenv
$ virtualenv env
$ source env/bin/activate
$ pip install pydomotic

    Next, install dependencies for each provider you intend to use. Only run the parts of the commands below that apply to your use case.

    $ pip install pydomotic[tuya]
$ pip install pydomotic[airthings]
$ pip install pydomotic[moen]
$ pip install pydomotic[fujitsu]

    Lastly, create your requirements.txt file by taking a snapshot of your virtual environment.

    $ pip freeze > requirements.txt

  6. Deploy your function.

    $ serverless deploy

Advanced

Providers

As described in CONFIGURATION.md, each IoT provider requires login credentials. For example, the tuya provider requires four credentials. When writing your pydomotic.yml file, you can tell pydomotic to load these values from plaintext or from environment variables. To load from environment use the ${env:ENV_VAR_NAME} pattern:

# pydomotic.yml

providers:
  tuya:
    username: ${env:TUYA_USERNAME}
    password: ${env:TUYA_PASSWORD}
    access_id: ${env:TUYA_ACCESS_ID}
    access_key: ${env:TUYA_ACCESS_KEY}

These environment variables will then need to be made available to your lambda function by specifying them in your serverless.yml file.

# serverless.yml

provider:
  name: aws
  environment:
    TUYA_USERNAME: ${env:TUYA_USERNAME}
    TUYA_PASSWORD: ${env:TUYA_PASSWORD}
    TUYA_ACCESS_ID: ${env:TUYA_ACCESS_ID}
    TUYA_ACCESS_KEY: ${env:TUYA_ACCESS_KEY}

If you are using source control (like git) for your serverless.yml file, it is highly recommended for security reasons not to commit these credentials. Instead, it is recommended that these secrets be loaded from local environment variables as shown in the example above. This means you will need to change your deploy command to:

$ TUYA_USERNAME='my-username' \
    TUYA_PASSWORD='my-password' \
    TUYA_ACCESS_ID='my-access-id' \
    TUYA_ACCESS_KEY='my-access-key' \
        serverless deploy

Timeout Settings

Since you won't be able to control the behavior of any 3rd party APIs, it is recommended that you set a timeout on your lambda function. Since AWS Lambda will retry any function that ends due to a raised exception. Therefore, it is important that should your function fail due to timeouts, it should not overlap with the next invocation one minute later.

For this reason, no more than a 30-second timeout is recommended. This can be set in the provider section of the serverless.yml file.

# serverless.yml

provider:
  name: aws
  timeout: 30  # seconds
  ...

To further manage for timeouts, it is also recommended that you configure timeout settings and data caching for providers and 3rd party APIs in your pydomotic.yml file.

# pydomotic.yml

triggers:
  ...
  weather:
    data_cache_seconds: 20

providers:
  tuya:
    ...
    device_status_cache_seconds: 20
    timeout_seconds: 5
  airthings:
    ...
    data_cache_seconds: 20
    timeout_seconds: 5

Deploying from Mac M1

When deploying from a computer with Apple's M1 processing chip, you will need to either cross compile dependencies or change the architecture of your deployed lambda function. The easiest way to do this is to add architecture: arm64 to the provider section of your serverless.yml file.

# serverless.yml

provider:
  name: aws
  architecture: arm64  # instruct lambda to use same processor type as your local computer
  ...

Loading config from S3

If you wish to store your pydomotic.yml file in AWS S3, you will need to instruct pydomotic how to find it.

After uploading your pydomotic.yml file to S3, update your serverless.yml file to give your lambda permission to read the file and tell pydomotic where to find it.

# serverless.yml

provider:
  name: aws
  ...
  environment:
    # bucket/key for your pydomotic.yml file in S3
    PYDOMOTIC_CONFIG_S3: home-automations/pydomotic.yml
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - 's3:GetObject'
          Resource:
            # arn for your pydomotic.yml file in S3
            - 'arn:aws:s3:::home-automations/pydomotic.yml'

package:
  patterns:
    - '!**'
    # 'pydomotic.yml' pattern removed

functions:
  cron:
    ...

Be sure to change the value home-automations/pydomotic.yml to match the bucket and key where you stored your file in S3.

Webhooks

If you wish to use the Webhook Trigger, you will need to specify a url for your lambda function.

# serverless.yml

functions:
  cron:
    handler: pydomotic.lambda_handler.handler
    url: true  # required for webhook trigger
    events:
      - schedule:
          rate: rate(1 minute)