Skip to main content
This guide will walk you through creating and running your first containerized application using Buildr.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.6 or higher installed
  • Docker installed and running
  • pip package manager

​
Create your first containerized app

1

Install Buildr

Install the metaparticle_pkg library using pip:
pip install metaparticle_pkg
Buildr is distributed as metaparticle_pkg on PyPI. The package includes Docker SDK for Python as a dependency.
2

Create your application

Create a new file called hello.py with the following code:
from metaparticle_pkg import Containerize
import time

@Containerize(
    package={'name': 'hello-app', 'repository': 'myrepo'}
)
def main():
    print('Hello from Buildr!')
    
    for i in range(10):
        print(f'Running for {i} seconds...')
        time.sleep(1)

if __name__ == '__main__':
    main()
The @Containerize decorator tells Buildr to:
  • Build a container image named myrepo/hello-app:latest
  • Run the application inside that container
3

Run your application

Execute your application:
python hello.py
You’ll see Buildr:
  1. Generate a Dockerfile
  2. Build the container image
  3. Run your application inside the container
  4. Stream the logs to your terminal
4

Verify the container

In another terminal, check that your container is running:
docker ps
You should see a container named hello-app in the list.

​
Add runtime configuration

Let’s create a web server with port configuration: 
from metaparticle_pkg import Containerize
from six.moves import SimpleHTTPServer, socketserver
import socket

@Containerize(
    package={'name': 'hello-web', 'repository': 'myrepo'},
    runtime={'ports': [8080]}
)
def main():
    class Handler(SimpleHTTPServer.SimpleHTTPRequestHandler):
        def do_GET(self):
            self.send_response(200)
            self.send_header("Content-type", "text/plain")
            self.end_headers()
            message = f"Hello from {socket.gethostname()}!\n"
            self.wfile.write(message.encode('UTF-8'))
    
    httpd = socketserver.TCPServer(("", 8080), Handler)
    print("Server running on port 8080")
    httpd.serve_forever()

if __name__ == '__main__':
    main()
The runtime parameter configures:
  • ports: Which ports to expose from the container
  • executor: Which runtime to use (docker or metaparticle)
  • replicas: Number of container instances to run
  • public: Whether to expose the service publicly

​
Publish to a registry

To publish your container image to Docker Hub or another registry: 
from metaparticle_pkg import Containerize

@Containerize(
    package={
        'name': 'hello-app',
        'repository': 'docker.io/yourusername',
        'publish': True  # Enable publishing
    }
)
def main():
    print('Hello from Buildr!')

if __name__ == '__main__':
    main()
Make sure you’re logged in to your container registry before setting publish: True:
docker login

​
Configuration options

The @Containerize decorator accepts two main parameters:

​
Package options

  • repository (required): Container registry repository
  • name: Container name (defaults to current directory name)
  • builder: Build system to use (default: ‘docker’)
  • publish: Whether to push to registry (default: False)
  • verbose: Enable verbose logging (default: True)
  • quiet: Suppress output (default: False)
  • py_version: Python version for base image (default: 3)

​
Runtime options

  • executor: Execution environment - ‘docker’ or ‘metaparticle’ (default: ‘docker’)
  • replicas: Number of container instances (default: 0)
  • ports: List of ports to expose (default: [])
  • public: Make service publicly accessible (default: False)

​
Next steps

Now that you’ve created your first containerized application, you can:
  • Explore advanced configuration options
  • Learn how to deploy with multiple replicas
  • Understand how Buildr generates Dockerfiles
  • Deploy to Kubernetes using the metaparticle executor

Build docs developers (and LLMs) love

Get started for freeTalk to us