Ephemeral Machines

It is possible to create a Teclada host that supports multiple instances. This is useful for connecting to ephemeral machines, such as Docker containers, Kubernetes pods, auto-scaling VMs, etc.

Steps

Create the Teclada host

Create a host on this page, and be sure to check the box 'Allow multiple instances'.
Store the generated token in an appropriate place, such as a Kubernetes secret.

Building the image

Modify your build scripts to perform these steps when building your VM or container image. (For example, add these commands to your Dockerfile).

Install dependencies. Many dependencies that normally come with full distributions aren't installed in container images. For apt-based dirtros, you'll need to run:
```
apt-get install -y curl ca-certificates gnupg
```
Fedora doesn't need any additional dependencies.
Install Teclada on your VM/container/etc. Follow the appropriate instructions for your package manager here. However, don't link the machine to your Teclada account with teclada setup when building the VM/container image.

Starting the container

When your container starts, it needs to start Teclada before running its regular code. Teclada provides a helper script for this, but you can use supervisord or write your own launcher instead.

Starting with `teclada_container_launcher`

This script registers and starts teclada in the background, then runs your regular code. Here's an example:

/bin/teclada_container_launcher --token=<your-token> --name=<name> -- /foo/bar/your-script

The --token and --name options can be provided via environment variables instead of flags. See the contents of teclada_container_launcher for a full description.

A Teclada instance started this way will automatically shut down when the main process exits. (The /foo/bar/your-script process in the example above.)

You can pass --silence to prevent Teclada from producing any output, or --logtostderr to produce extra output for debugging. (This output is also written to /var/log/teclada.log by default.)

Starting manually

Teclada must be configured, then run in the background. While you could do this with teclada configure and something like (nohup teclada &) > /var/log/teclada.log 2>&1, there's a better way.

The bg_run command starts Teclada in the background. If a -- separator is specified followed by a command, that command will be run in the foreground after Teclada has been started in the background. When that foreground command exits, Teclada will exit as well.

The oneshot command combines the configure command and the run command into a single operation that performs both.

The bg_oneshot command combines configure with bg_run.

Examples

Add your existing ENTRYPOINT after the -- argument in these scripts.

While these scripts specify --token and --name by flag, Teclada recommends you specify them via file or environment variable. See teclada_container_launcher for details. We recommend that name be something that uniquely identifies this particular instance, such as a Kubernetes pod name.

Ubuntu Dockerfile

FROM ubuntu:22.04

RUN apt-get update; apt-get install -y curl ca-certificates gnupg

RUN curl -s https://app.teclada.com/apt_setup.sh | bash; apt-get install -y teclada

ENTRYPOINT ["/bin/teclada_container_launcher", "--token=foo", "--name=bar", "--"]

Fedora Dockerfile

FROM fedora:37

RUN curl -s https://app.teclada.com/rpm_setup.sh | bash; dnf install -y teclada

ENTRYPOINT ["/bin/teclada_container_launcher", "--token=foo", "--name=bar", "--"]

Kubernetes YAML

This YAML file specifies a minimum deployment that injects the Teclada token and the pod name into each container. teclada_container_launcher will read these and use them automatically. This is fully working when used in combination with the ubuntu dockerfile above (sans entrypoint).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: teclada-example
spec:
  selector:
    matchLabels:
      run: teclada-example
  replicas: 1
  template:
    metadata:
      labels:
        run: teclada-example
    spec:
      containers:
      - name: teclada-example
        image: registry.digitalocean.com/teclada/ex_ubuntu  # Your image here
        imagePullPolicy: Always
        command: ["/bin/teclada_container_launcher"]
        args: ["--logtostderr", 
          "--",
          # Your command & arguments here
          "sleep",
          "40000"  
        ]
        
        # Configuration can be injected via environment variable...
        env:
        - name: KUBERNETES_POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name

        # ...Or via file
        volumeMounts:
        - name: tecladatoken
          mountPath: "/etc/teclada_cfg"
          readOnly: true

      volumes:
      - name: tecladatoken
        secret:
          secretName: teclada-token
          optional: false
          items:
          - key: teclada-token
            path: token