imgmaid

A self-hosted image hosting solution, inspired by Picsur, with S3 backend support.

Quick Start (Docker)

1. Create a .env file in the root directory with your S3 credentials:

   AWS_ACCESS_KEY_ID=your_key
   AWS_SECRET_ACCESS_KEY=your_secret
   S3_BUCKET_NAME=your_bucket
   S3_ENDPOINT_URL=https://s3.amazonaws.com
   AWS_REGION=us-east-1
   

2. Run with Docker Compose:

   docker compose up -d
   

   The application will be available at http://localhost:8000. Data will be persisted in the ./data directory.

3. Retrieve Admin Password:

   docker compose logs imgmaid | grep "Password:" -A 5 -B 5
   

4. Login: Use username admin and the password from the logs.

Features

• S3 Storage Backend: Reliable and scalable storage.
• Secure Public IDs: Images use UUIDs (/image/uuid) instead of sequential IDs to prevent enumeration.
• Smart Caching: Processed image variations are cached in S3 to minimize processing overhead.
• Dynamic Image Conversion: Powered by ImgProxy. Access images as /{id}.{ext} (e.g., .png, .webp) for on-the-fly conversion.
• ShareX Integration: Generate and download config directly from the UI.
• Admin Dashboard: Manage system settings, users, and roles.
• Image Upload: Drag & Drop interface with API Key authentication.
• Gallery View: Browse uploaded images (requires login).

---

Advanced Documentation

System Configuration

Most application settings (JWT expiry, image conversion timeouts, etc.) are managed via the Admin Dashboard -> System Settings. Environment variables are primarily used for infrastructure connection details (S3, Database, ImgProxy).

ShareX Setup

1. Go to the web interface and log in.
2. Navigate to Settings.
3. Under the ShareX Configuration section, select your API Key.
4. Click the Download Config button to get the .sxcu file.
5. Import the file into ShareX.

Database Options

imgmaid uses SQLite by default, which is sufficient for most single-instance deployments. However, it also supports PostgreSQL and MySQL/MariaDB for more robust setups.

Switching Databases

1. Open docker-compose.yml.
2. Uncomment the desired database service (e.g., postgres or mariadb) at the bottom of the file.
3. Uncomment the corresponding DATABASE_URL in the imgmaid service environment variables.
4. Comment out the default SQLite DATABASE_URL.
5. Restart the container: docker compose up -d

Note: MongoDB is not currently supported as the application uses a SQL-based ORM (SQLModel).

Manual Setup (Development)

If you want to run the backend and frontend manually for development:

Backend

1. Navigate to backend/
2. Create a virtual environment: python -m venv venv
3. Activate it: source venv/bin/activate
4. Install dependencies: pip install -r requirements.txt
5. Set environment variables (create a .env file or export them):

   export AWS_ACCESS_KEY_ID=your_key
   export AWS_SECRET_ACCESS_KEY=your_secret
   export S3_BUCKET_NAME=your_bucket
   export S3_ENDPOINT_URL=https://s3.amazonaws.com # or your minio url
   export AWS_REGION=us-east-1 # Optional, leave empty if not needed
   export S3_FORCE_PATH_STYLE=false # Set to true for MinIO or other S3-compatibles
   export FRONTEND_URL=http://localhost:5173
   export API_URL=http://localhost:8000
   # ImgProxy Config (Optional for local dev if not running imgproxy)
   export IMGPROXY_URL=http://localhost:8080
   export IMGPROXY_KEY=your_key
   export IMGPROXY_SALT=your_salt
   

6. Run the server: uvicorn app.main:app --reload

Frontend

1. Navigate to frontend/
2. Install dependencies: npm install
3. Run the dev server: npm run dev

CI/CD

• Woodpecker CI: .woodpecker.yml is configured to build and push images. Update the registry settings in the file.

Architecture

• Backend: FastAPI, SQLModel, Boto3
• Frontend: React, Vite, MUI (Material UI)
• Database: SQLite (default), PostgreSQL, MySQL/MariaDB