Deploying SAMA

Introduction

SAMA (Simple Annotation for Machine-learning Applications) is a self-hosted image annotation tool designed to streamline the creation of training datasets for machine learning and computer vision projects. It provides an intuitive web interface for labeling images with bounding boxes, polygons, keypoints, and semantic segmentation masks.

Built with modern web technologies, SAMA offers a responsive annotation experience that works across devices. The application focuses on simplicity while providing the essential features needed for professional annotation workflows, making it accessible to both individual researchers and teams working on computer vision projects.

Key highlights of SAMA:

• Multiple Annotation Types: Support for bounding boxes, polygons, polylines, keypoints, and semantic segmentation
• Intuitive Interface: Clean, distraction-free annotation workspace with keyboard shortcuts
• Project Management: Organize annotations into projects with custom label configurations
• Export Formats: Export annotations in popular formats including COCO, YOLO, and Pascal VOC
• Team Collaboration: Share projects with team members and track annotation progress
• Image Management: Upload and organize images directly through the web interface
• Undo/Redo Support: Full history tracking for annotation actions
• Zoom and Pan: Navigate large images with smooth zoom and pan controls
• Auto-Save: Automatic saving of annotations to prevent data loss
• Self-Hosted Privacy: Keep your training data secure on your own infrastructure

This guide walks through deploying SAMA on Klutch.sh using Docker, configuring persistent storage for your image datasets, and setting up the application for production annotation workflows.

Why Deploy SAMA on Klutch.sh

Deploying SAMA on Klutch.sh provides several advantages for machine learning teams:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds SAMA without complex orchestration. Push to GitHub, and your annotation platform deploys automatically.

Persistent Storage: Attach persistent volumes for your image datasets, annotations, and project configurations. Your training data survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your annotation platform and protecting your proprietary datasets.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments, keeping your deployment synchronized.

Scalable Resources: Allocate CPU and memory based on your annotation workload. Handle large image datasets and multiple concurrent annotators.

Team Access: Provide secure, browser-based access to your annotation platform for distributed teams without VPN configuration.

Always-On Availability: Your annotation platform remains accessible 24/7, enabling asynchronous collaboration across time zones.

Prerequisites

Before deploying SAMA on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your SAMA configuration
• Basic familiarity with Docker and containerization concepts
• Image datasets ready for annotation
• (Optional) A custom domain for your SAMA instance

Deploying SAMA on Klutch.sh

Create Your Repository

Create a new GitHub repository for your SAMA deployment. Add a Dockerfile with the following content:

FROM ghcr.io/bitswan-space/sama:latest

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

Push to GitHub

Commit and push your Dockerfile to your GitHub repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “sama” or “image-annotation”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your SAMA Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
NODE_ENV	production
SECRET_KEY	A secure random string for session encryption

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/app/data	10 GB	Application data and configuration
/app/uploads	100+ GB	Uploaded images for annotation
/app/exports	10 GB	Exported annotation files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision HTTPS.

Access SAMA

Once deployment completes, access your SAMA instance at the provided URL. Create your first project and begin annotating images.

Initial Configuration

Creating Your First Project

After accessing SAMA:

1. Click New Project on the dashboard
2. Enter a project name and description
3. Configure label classes for your annotation task
4. Set annotation type (bounding box, polygon, etc.)
5. Upload your initial image dataset

Configuring Label Classes

Define your label schema:

1. Navigate to project settings
2. Add label classes with names and colors
3. Configure keyboard shortcuts for quick labeling
4. Set up hierarchical labels if needed

Team Management

Invite collaborators to your annotation projects:

1. Go to project settings
2. Add team members by email
3. Assign roles (admin, annotator, reviewer)
4. Set up annotation guidelines

Best Practices

Annotation Workflow

• Establish Guidelines: Create clear annotation guidelines for consistency
• Use Keyboard Shortcuts: Speed up annotation with built-in shortcuts
• Regular Exports: Export annotations regularly for backup
• Quality Review: Implement review processes for annotation quality

Data Management

• Organize by Project: Keep datasets organized in separate projects
• Backup Exports: Store exported annotations in version control
• Image Preprocessing: Resize large images before uploading for better performance

Troubleshooting

Images Not Loading

• Verify volume mounts are correctly configured
• Check file permissions on uploaded images
• Ensure sufficient storage space on volumes

Export Failures

• Confirm export directory has write permissions
• Check for sufficient disk space
• Review application logs for specific errors

Additional Resources

• SAMA GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying SAMA on Klutch.sh provides a streamlined solution for self-hosted image annotation. With persistent storage for your datasets, automatic HTTPS, and easy team access, you can focus on building quality training data for your machine learning projects rather than managing infrastructure.