Deploying elixire

Introduction

elixire is a self-hosted file hosting and URL shortening service that provides a privacy-focused alternative to public file sharing platforms. Built with Python and designed for simplicity, elixire allows you to upload and share files, images, and text snippets while maintaining complete control over your data.

Originally developed as a community project, elixire offers a clean, fast interface for file uploads with features like automatic file expiration, ShareX integration, and customizable shortlinks. The application is designed to be lightweight and easy to deploy while still providing all the essential features needed for personal or small team file sharing.

Key highlights of elixire:

File Hosting: Upload and share any file type with direct download links
Image Hosting: Share images with automatic thumbnail generation
URL Shortening: Create short, memorable links for any URL
Text Paste: Share code snippets and text with syntax highlighting
ShareX Integration: Native support for ShareX screenshot tool
Automatic Expiration: Set files to automatically delete after a specified time
User Accounts: Multi-user support with individual storage quotas
API Access: Full REST API for programmatic uploads
Privacy-Focused: No tracking, no ads, your data stays yours
100% Open Source: Licensed under AGPL-3.0

This guide walks through deploying elixire on Klutch.sh using Docker, configuring storage and user management, and integrating with upload tools like ShareX.

Why Deploy elixire on Klutch.sh

Deploying elixire on Klutch.sh provides several advantages for your file hosting needs:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds elixire without complex orchestration. Push to GitHub, and your file hosting service deploys automatically.

Persistent Storage: Attach persistent volumes for your uploaded files and database. Your files survive container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure file uploads and downloads from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Scalable Resources: Allocate CPU, memory, and storage based on your usage. Start small and scale up as your file hosting needs grow.

Environment Variable Management: Securely store sensitive configuration like database credentials and API keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your elixire instance for short, memorable file sharing URLs.

Always-On Availability: Your file hosting service remains accessible 24/7 without managing your own hardware.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your elixire configuration
Basic familiarity with Docker and containerization concepts
(Optional) ShareX or similar screenshot/upload tool
(Optional) A custom domain for short URLs

Understanding elixire Architecture

elixire is built on a straightforward architecture:

Python Backend: The core application runs on Python with aiohttp for asynchronous HTTP handling, providing fast and efficient file uploads and downloads.

PostgreSQL Database: User accounts, file metadata, and URL mappings are stored in PostgreSQL. The database tracks upload history, expiration dates, and user quotas.

File Storage: Uploaded files are stored on the filesystem in a configurable directory. Files are organized by upload hash for deduplication and efficient retrieval.

Redis (Optional): Can be used for caching and session management to improve performance under load.

API-First Design: The REST API allows integration with various upload tools and custom clients.

Preparing Your Repository

To deploy elixire on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

elixire-deploy/
├── Dockerfile
├── config.py
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    libpq-dev \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Clone elixire repository
RUN git clone https://gitlab.com/elixire/elixire.git .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Create directories for uploads and data
RUN mkdir -p /data/uploads /data/thumbnails

# Set environment variables
ENV ELIXIRE_CONFIG=/app/config.py
ENV UPLOAD_FOLDER=/data/uploads
ENV THUMBNAIL_FOLDER=/data/thumbnails

# Expose the application port
EXPOSE 8080

# Run the application
CMD ["python", "-m", "elixire"]

Advanced Dockerfile with Custom Configuration

For more control over your deployment:

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    libpq-dev \
    gcc \
    libmagic1 \
    && rm -rf /var/lib/apt/lists/*

# Clone elixire
RUN git clone https://gitlab.com/elixire/elixire.git .

# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Create data directories
RUN mkdir -p /data/uploads /data/thumbnails /data/logs

# Copy custom configuration
COPY config.py /app/config.py

# Set environment variables
ENV ELIXIRE_CONFIG=/app/config.py
ENV UPLOAD_FOLDER=/data/uploads
ENV THUMBNAIL_FOLDER=/data/thumbnails
ENV DATABASE_URL=${DATABASE_URL}
ENV SECRET_KEY=${SECRET_KEY}

# Set proper permissions
RUN chmod -R 755 /data

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

EXPOSE 8080

CMD ["python", "-m", "elixire"]

Creating the Configuration File

Create a config.py file for elixire settings:

import os

# Database configuration
DATABASE_URL = os.environ.get('DATABASE_URL', 'postgresql://elixire:password@localhost/elixire')

# Secret key for session encryption
SECRET_KEY = os.environ.get('SECRET_KEY', 'change-this-in-production')

# Site configuration
SITE_NAME = os.environ.get('SITE_NAME', 'elixire')
SITE_URL = os.environ.get('SITE_URL', 'https://your-domain.com')

# Upload settings
UPLOAD_FOLDER = os.environ.get('UPLOAD_FOLDER', '/data/uploads')
THUMBNAIL_FOLDER = os.environ.get('THUMBNAIL_FOLDER', '/data/thumbnails')
MAX_CONTENT_LENGTH = int(os.environ.get('MAX_UPLOAD_SIZE', 100)) * 1024 * 1024  # MB to bytes

# File expiration (in days, 0 for never)
DEFAULT_EXPIRY = int(os.environ.get('DEFAULT_EXPIRY', 0))
MAX_EXPIRY = int(os.environ.get('MAX_EXPIRY', 365))

# User settings
REGISTRATION_ENABLED = os.environ.get('REGISTRATION_ENABLED', 'true').lower() == 'true'
DEFAULT_QUOTA = int(os.environ.get('DEFAULT_QUOTA', 1024))  # MB

# API settings
API_ENABLED = os.environ.get('API_ENABLED', 'true').lower() == 'true'

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
__pycache__
*.pyc

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`SECRET_KEY`	Yes	-	Secret key for session encryption
`SITE_NAME`	No	elixire	Name displayed in the UI
`SITE_URL`	Yes	-	Public URL of your instance
`MAX_UPLOAD_SIZE`	No	100	Maximum upload size in MB
`DEFAULT_EXPIRY`	No	0	Default file expiration in days
`MAX_EXPIRY`	No	365	Maximum allowed expiration
`REGISTRATION_ENABLED`	No	true	Allow new user registration
`DEFAULT_QUOTA`	No	1024	Default storage quota in MB
`API_ENABLED`	No	true	Enable API access

Deploying elixire on Klutch.sh

Once your repository is prepared, follow these steps to deploy elixire:

Generate Your Secret Key

Before deployment, generate a secure secret key:

python -c "import secrets; print(secrets.token_hex(32))"

Save this key securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.py .dockerignore README.md
git commit -m "Initial elixire deployment configuration"
git remote add origin https://github.com/yourusername/elixire-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “elixire” or “files”.

Create a PostgreSQL Database

Before creating the elixire app, set up a PostgreSQL database:

Within your project, create a new PostgreSQL database service
Note the connection string provided by Klutch.sh
This will be used for the DATABASE_URL environment variable

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 elixire Dockerfile.

Configure HTTP Traffic

elixire serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
`DATABASE_URL`	PostgreSQL connection string from step 4
`SECRET_KEY`	Your generated secret key from step 1
`SITE_URL`	`https://your-app-name.klutch.sh`
`SITE_NAME`	Your preferred site name
`MAX_UPLOAD_SIZE`	`100` (or your preferred limit in MB)
`REGISTRATION_ENABLED`	`true` or `false`

Attach Persistent Volumes

Persistent storage is essential for elixire. Add the following volumes:

Mount Path	Recommended Size	Purpose
`/data/uploads`	50+ GB	Uploaded files storage
`/data/thumbnails`	5 GB	Generated thumbnails
`/data/logs`	1 GB	Application logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the elixire container
Provision an HTTPS certificate

Access elixire

Once deployment completes, access your elixire instance at https://your-app-name.klutch.sh. Create an admin account to begin using the service.

Initial Setup and Configuration

Creating the Admin Account

When you first access your elixire instance:

Click on “Register” to create a new account
The first registered user typically becomes the administrator
Set a strong password for your admin account
Verify your account if email verification is enabled

Configuring User Settings

As an administrator, configure user management:

Access the admin panel
Set default storage quotas for new users
Configure registration settings (open, invite-only, or disabled)
Set up user roles and permissions

Setting Up File Retention

Configure how long files are kept:

Set default expiration periods for uploads
Configure maximum allowed retention time
Set up automatic cleanup for expired files

ShareX Integration

Configuring ShareX

ShareX is a popular screenshot and file upload tool that integrates well with elixire:

Open ShareX and go to Destinations > Custom uploader settings
Create a new uploader with the following settings:

Setting	Value
Name	elixire
Destination type	Image uploader, Text uploader, File uploader
Request method	POST
Request URL	`https://your-domain.com/api/upload`
Body	Form data (multipart/form-data)

Add a file form field named file
Add an authorization header with your API key
Set the URL field to $json:url$

Obtaining Your API Key

To get your API key for ShareX:

Log into your elixire account
Go to Settings > API
Generate a new API key
Copy the key to your ShareX configuration

Testing the Integration

Verify your ShareX setup:

Take a screenshot using ShareX
Confirm the upload completes successfully
Verify the returned URL works

URL Shortening

Creating Short URLs

elixire includes URL shortening functionality:

Navigate to the URL shortening page
Enter the long URL you want to shorten
Optionally specify a custom short code
Click “Shorten” to create the short URL

Managing Short URLs

Track and manage your shortened URLs:

View click statistics for each URL
Edit or delete existing short URLs
Set expiration dates for temporary links

Text Paste Feature

Creating Text Pastes

Share code snippets and text:

Navigate to the paste section
Enter or paste your text content
Select syntax highlighting language (optional)
Set expiration and visibility options
Create the paste and share the URL

Syntax Highlighting

Supported languages include:

Python, JavaScript, TypeScript
HTML, CSS, JSON, YAML
Bash, PowerShell
SQL, Markdown
And many more

User Management

User Registration

Control who can use your instance:

Mode	Description
Open	Anyone can register
Invite-Only	Users need an invite code
Disabled	Admin manually creates accounts

Storage Quotas

Manage user storage:

Set default quota for new users
Adjust individual user quotas as needed
Monitor storage usage across accounts
Set up alerts for quota limits

User Roles

Configure user permissions:

Role	Capabilities
Admin	Full access, user management
User	Upload, manage own files
Guest	View shared content only

Production Best Practices

Security Recommendations

Strong Secret Key: Use a cryptographically secure random key
HTTPS Only: Ensure all traffic uses HTTPS (automatic with Klutch.sh)
API Key Security: Treat API keys like passwords
Regular Updates: Keep elixire updated for security patches
Access Control: Limit registration if running for personal use

Performance Optimization

Storage Sizing: Allocate sufficient storage for your expected uploads
Database Tuning: Configure PostgreSQL for your usage patterns
Thumbnail Generation: Enable lazy thumbnail generation for large libraries
CDN Integration: Consider a CDN for high-traffic file serving

Backup Strategy

Protect your uploaded files and data:

Database Backups: Regular PostgreSQL backups
File Backups: Backup the uploads directory
Configuration: Version control your config.py
Test Restores: Periodically verify backup integrity

Monitoring and Logging

Accessing Logs

View application logs through:

Klutch.sh Dashboard: View runtime logs
Log Volume: Access /data/logs for persistent logs
Database Logs: PostgreSQL logging for query issues

Usage Statistics

Monitor your elixire instance:

Track total storage used
Monitor upload/download activity
Review user registration trends
Check for failed upload attempts

Troubleshooting Common Issues

Upload Failures

Symptoms: Files fail to upload or timeout.

Solutions:

Check file size against MAX_UPLOAD_SIZE limit
Verify storage volume has available space
Review application logs for specific errors
Check network connectivity

Database Connection Issues

Symptoms: Application fails to start or shows database errors.

Solutions:

Verify DATABASE_URL is correct
Ensure PostgreSQL service is running
Check database user permissions
Review PostgreSQL logs for connection issues

ShareX Upload Fails

Symptoms: ShareX shows upload errors.

Solutions:

Verify API key is correct and active
Check ShareX custom uploader configuration
Ensure the API endpoint URL is correct
Test with a small file first

Thumbnails Not Generating

Symptoms: Images upload but thumbnails don’t appear.

Solutions:

Verify thumbnail directory is writable
Check available disk space
Ensure image processing libraries are installed
Review logs for thumbnail generation errors

Updating elixire

To update to a newer version:

Check for Updates: Review the elixire repository for new releases
Update Dockerfile: Modify to pull the latest version
Push Changes: Commit and push to trigger redeployment
Run Migrations: Apply any database migrations if required
Verify: Test uploads and downloads after update

Additional Resources

Conclusion

Deploying elixire on Klutch.sh gives you a powerful, self-hosted file hosting platform with automatic builds, persistent storage, and secure HTTPS access. The combination of elixire’s feature-rich file sharing capabilities and Klutch.sh’s deployment simplicity means you can focus on sharing files rather than managing infrastructure.

With support for file uploads, image hosting, URL shortening, and text pastes, elixire on Klutch.sh provides a comprehensive file sharing solution that respects your privacy. Whether you’re sharing screenshots, distributing files, or creating short URLs, elixire delivers the functionality you need with complete control over your data.