Deploying Picsur

Introduction

Picsur is a simple, self-hosted image hosting service designed for easy deployment and use. With a clean, modern interface, Picsur allows you to upload, store, and share images through shareable links. The application includes automatic image compression, format conversion, and integration with popular tools like ShareX.

Built with NestJS for the backend and Angular for the frontend, Picsur provides a robust yet lightweight solution for personal image hosting. The application uses PostgreSQL for metadata storage and supports various image formats with automatic optimization.

Key highlights of Picsur:

Simple Upload: Drag-and-drop or click to upload images
Automatic Compression: Optimize images automatically
Format Conversion: Convert between image formats on-the-fly
ShareX Integration: Compatible with ShareX for quick uploads
User Accounts: Multi-user support with roles
API Access: RESTful API for programmatic uploads
Image Gallery: Browse all uploaded images
Delete Functionality: Remove images with delete links
EXIF Stripping: Remove metadata for privacy
Responsive Design: Works on desktop and mobile
100% Open Source: GPL-3.0 licensed

This guide walks through deploying Picsur on Klutch.sh using Docker, configuring the database, and setting up the application for production use.

Why Deploy Picsur on Klutch.sh

Deploying Picsur on Klutch.sh provides several advantages for image hosting:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Picsur without complex orchestration. Push to GitHub and your image host deploys automatically.

Persistent Storage: Attach persistent volumes for your images and database. Your data survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure image uploads and serving.

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

Scalable Resources: Allocate CPU and memory based on expected traffic and image processing needs.

Environment Variable Management: Securely store database credentials through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Picsur instance for branded image hosting.

Always-On Availability: Your image host remains accessible 24/7 without managing infrastructure.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Picsur configuration
A PostgreSQL database
Basic familiarity with Docker and containerization concepts
(Optional) A custom domain for your Picsur instance

Understanding Picsur Architecture

Picsur is built on a modern stack:

NestJS Backend: The server handles image uploads, processing, and API requests.

Angular Frontend: The web interface provides a responsive single-page application experience.

PostgreSQL Database: Stores user accounts, image metadata, and configuration.

Sharp Image Processing: Uses Sharp for efficient image manipulation and optimization.

Preparing Your Repository

To deploy Picsur on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

picsur-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/carambs/picsur:latest

# Environment variables
ENV PICSUR_HOST=0.0.0.0
ENV PICSUR_PORT=8080
ENV PICSUR_DB_HOST=${PICSUR_DB_HOST}
ENV PICSUR_DB_PORT=${PICSUR_DB_PORT:-5432}
ENV PICSUR_DB_USERNAME=${PICSUR_DB_USERNAME}
ENV PICSUR_DB_PASSWORD=${PICSUR_DB_PASSWORD}
ENV PICSUR_DB_DATABASE=${PICSUR_DB_DATABASE:-picsur}
ENV PICSUR_ADMIN_USERNAME=${PICSUR_ADMIN_USERNAME:-admin}
ENV PICSUR_ADMIN_PASSWORD=${PICSUR_ADMIN_PASSWORD}
ENV PICSUR_JWT_SECRET=${PICSUR_JWT_SECRET}

EXPOSE 8080

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

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Environment Variables Reference

Variable	Required	Default	Description
`PICSUR_DB_HOST`	Yes	-	PostgreSQL host
`PICSUR_DB_PORT`	No	5432	PostgreSQL port
`PICSUR_DB_USERNAME`	Yes	-	Database username
`PICSUR_DB_PASSWORD`	Yes	-	Database password
`PICSUR_DB_DATABASE`	No	picsur	Database name
`PICSUR_ADMIN_USERNAME`	No	admin	Admin username
`PICSUR_ADMIN_PASSWORD`	Yes	-	Admin password
`PICSUR_JWT_SECRET`	Yes	-	JWT signing secret

Deploying Picsur on Klutch.sh

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

Provision a PostgreSQL Database

Set up a PostgreSQL database for Picsur. Create a database and user with full access permissions.

Generate a JWT Secret

Create a secure secret for JWT signing:

openssl rand -base64 32

Store this securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Picsur deployment configuration"
git remote add origin https://github.com/yourusername/picsur-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 “picsur” or “image-host”.

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

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080 (Picsur’s default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
`PICSUR_DB_HOST`	Your PostgreSQL host
`PICSUR_DB_USERNAME`	Database username
`PICSUR_DB_PASSWORD`	Database password
`PICSUR_DB_DATABASE`	`picsur`
`PICSUR_ADMIN_PASSWORD`	Your admin password
`PICSUR_JWT_SECRET`	Your generated secret

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
`/picsur/data`	50+ GB	Image storage

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 Picsur container
Provision an HTTPS certificate

Access Picsur

Once deployment completes, access your Picsur instance at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Access the admin interface:

Navigate to your Picsur URL
Click “Login”
Enter admin username and password
Access the admin dashboard

Configuring Settings

Adjust application settings:

Navigate to Settings
Configure upload limits
Set image compression options
Configure user registration

User Management

Create and manage user accounts:

Go to User Management
Create new users
Assign roles and permissions
Manage existing accounts

Using Picsur

Uploading Images

Upload images through the web interface:

Navigate to the upload page
Drag and drop or click to select
Image uploads and processes
Receive shareable link

ShareX Integration

Configure ShareX for quick uploads:

Open ShareX
Add custom uploader
Configure endpoint and authentication
Upload directly from desktop

API Access

Use the API for programmatic uploads:

Authenticate to get token
POST images to upload endpoint
Receive image URL in response

Production Best Practices

Security Recommendations

Strong Passwords: Use complex passwords for admin and users
JWT Secret: Use a secure, random JWT secret
Database Security: Secure database connections
Regular Updates: Keep Picsur updated

Storage Management

Monitor Usage: Track storage consumption
Cleanup: Remove unused images periodically
Compression: Configure appropriate compression levels
Volume Sizing: Size volume for expected usage

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Application fails to start.

Solutions:

Verify database credentials
Check database host accessibility
Confirm database exists
Review connection string format

Upload Failures

Symptoms: Images fail to upload.