Deploying Sandstorm

Introduction

Sandstorm is a self-hosted web productivity suite that lets you run web applications in secure sandboxes. Each document, project, or task runs in its own isolated container with its own data, providing security by default without complex administration.

The platform revolutionizes self-hosting by making it as easy to install applications as clicking a button. Sandstorm’s unique security model treats each piece of data as a separate grain that can be shared with specific people or groups, enabling fine-grained access control without traditional user management.

Key highlights of Sandstorm:

• App Marketplace: One-click installation of applications
• Security Sandboxing: Each grain runs in isolation
• Capability-Based Security: Share by URL, no user management
• Zero Administration Apps: Apps require no configuration
• Backup and Restore: Export grains with one click
• OAuth Integration: Login with Google, GitHub, or email
• Fine-Grained Sharing: Share individual documents
• Automatic Updates: Apps update seamlessly
• Open Source Apps: Growing library of available apps
• LDAP/SAML Support: Enterprise authentication

This guide walks through deploying Sandstorm on Klutch.sh using Docker, installing applications, and managing your productivity suite.

Why Deploy Sandstorm on Klutch.sh

Deploying Sandstorm on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh builds your Sandstorm configuration automatically.

Persistent Storage: Attach volumes for grains and application data.

HTTPS by Default: Secure access with automatic SSL certificates.

GitHub Integration: Version control your configuration.

Scalable Resources: Allocate resources based on usage.

Always-On Access: 24/7 availability for your productivity tools.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository
• Basic familiarity with Docker
• A custom domain (recommended for Sandstorm)
• (Optional) OAuth credentials for authentication

Deploying Sandstorm on Klutch.sh

Create Your Repository

Create a new GitHub repository for your Sandstorm deployment. Add a Dockerfile:

FROM buildpack-deps:focal

RUN apt-get update && apt-get install -y \
    curl \
    xz-utils \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /opt

RUN curl https://install.sandstorm.io/ | bash -s -- -d -p 6080

ENV PORT=6080

EXPOSE 6080

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:6080/ || exit 1

CMD ["/opt/sandstorm/sandstorm", "start", "-n"]

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.

Create a New App

Within your project, create a new app. Connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Configure Sandstorm settings:

Variable	Value
BASE_URL	Your deployment URL
WILDCARD_HOST	*.your-domain.com

Attach Persistent Volumes

Add volumes for data:

Mount Path	Recommended Size	Purpose
/opt/sandstorm	50 GB	Sandstorm installation
/var/sandstorm	100 GB	Grain storage

Deploy Your Application

Click Deploy to start the build process.

Complete Setup

Access your deployment and complete initial configuration.

Initial Configuration

First-Time Setup

Configure Sandstorm:

1. Access your Sandstorm URL
2. Set up admin account
3. Configure authentication methods
4. Set server title

Wildcard DNS

Sandstorm requires wildcard DNS:

• Configure *.sandstorm.yourdomain.com
• Point to your deployment
• Required for grain isolation

Authentication

Email Login

Simple email-based authentication:

1. Users enter email
2. Receive login link
3. Click to authenticate

OAuth Providers

Configure social login:

• Google
• GitHub
• LDAP/SAML for enterprise

Enterprise Authentication

Configure LDAP:

1. Access admin settings
2. Configure LDAP connection
3. Map user attributes
4. Test authentication

Installing Applications

App Market

Browse and install apps:

1. Click Apps in navigation
2. Browse available applications
3. Click Install on desired app
4. App is ready immediately

Popular Applications

Available on Sandstorm:

• Etherpad: Collaborative documents
• Wekan: Kanban boards
• Rocket.Chat: Team messaging
• GitWeb: Git repository viewer
• draw.io: Diagramming tool
• Davros: File sharing

Uploading SPK Files

Install custom apps:

1. Obtain SPK file
2. Go to Apps page
3. Upload SPK
4. App becomes available

Grains

Creating Grains

Each grain is a document/instance:

1. Open an installed app
2. Click Create New
3. Grain is created
4. Begin working

Sharing Grains

Share with specific people:

1. Open grain
2. Click Share button
3. Enter email addresses
4. Set permission level
5. Send share link

Grain Permissions

Control access levels:

Level	Capabilities
Viewer	Read-only access
Editor	Modify content
Owner	Full control including sharing

Exporting Grains

Backup individual grains:

1. Open grain menu
2. Click Download Backup
3. Save ZIP file
4. Restore anytime

Security Model

Sandboxing

Each grain runs isolated:

• Separate filesystem
• No network by default
• Limited capabilities
• Secure communication

Capability Security

Permission via possession:

• Having URL = having permission
• Revoke by deleting share
• No user database needed
• Simple sharing model

Administration

User Management

Manage platform users:

1. Access Admin panel
2. View user list
3. Manage permissions
4. Invite new users

Resource Limits

Configure quotas:

• Storage per user
• Grain counts
• Compute resources

Monitoring

Track usage:

• Active grains
• Storage consumption
• User activity

Customization

Branding

Customize appearance:

1. Access Admin settings
2. Set server title
3. Configure colors
4. Add custom CSS

Feature Flags

Enable/disable features:

• App market access
• Demo accounts
• Self-registration

Backup and Recovery

Full Backup

Back up entire installation:

sandstorm backup /path/to/backup.tar.gz

Grain Backups

Individual grain export:

• User-initiated backups
• Automated via API
• Restore to any Sandstorm

Troubleshooting

Grain Won’t Start

• Check resource limits
• Verify app installation
• Review logs
• Restart Sandstorm

Authentication Issues

• Verify OAuth credentials
• Check email delivery
• Review authentication logs

Performance

• Monitor resource usage
• Check grain count
• Optimize storage

Additional Resources

• Sandstorm Official Website
• Sandstorm Documentation
• Sandstorm GitHub Repository
• Sandstorm App Market
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Sandstorm on Klutch.sh provides a unique, secure platform for self-hosted web applications. With its innovative security model, one-click app installation, and fine-grained sharing, Sandstorm simplifies self-hosting while providing enterprise-grade security. Combined with Klutch.sh’s reliable hosting, you get an always-available productivity suite that puts you in control of your data.