PostOwl Example Application on Clever Cloud

This is an example of deploying PostOwl on Clever Cloud with automatic SQLite backups to Cellar S3 using Litestream.

PostOwl is a self-hosted platform for blogging, sharing posts with friends via secret links, and maintaining private journals.

About the Application

PostOwl is installed from source and runs on Clever Cloud's Node.js runtime. It uses:

• SvelteKit with adapter-node for the web application
• SQLite (better-sqlite3) for the database
• Litestream for continuous SQLite replication to Cellar S3
• Nodemailer for email notifications

Features

• Blog with public and private posts
• Share posts with friends via secret links with email notifications
• In-place content editing with a rich text editor (ProseMirror)
• Private journal/diary
• Asset storage (images) in SQLite

Technology Stack

• SvelteKit - Web framework
• SQLite (better-sqlite3) - Database
• Litestream - SQLite replication to S3
• Cellar - S3-compatible object storage by Clever Cloud

Prerequisites

• Node.js 24+
• npm
• A Clever Cloud account
• A Cellar S3 add-on (for Litestream backups)

Running the Application Locally

# Clone PostOwl
git clone https://github.com/PostOwl/postowl.git
cd postowl

# Install dependencies
npm install

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your settings

# Initialize the database
sqlite3 data/db.sqlite3 < scripts/schema.sql

# Start development server
npm run dev

The application will be accessible at http://localhost:5173.

Deploying on Clever Cloud

You have two options to deploy your application on Clever Cloud: using the Web Console or using the Clever Tools CLI.

Option 1: Deploy using the Web Console

1. Create an account on Clever Cloud

If you don't already have an account, go to the Clever Cloud console and follow the registration instructions.

2. Fork and clone PostOwl

Fork the PostOwl repository and clone your fork:

git clone https://github.com/<your-username>/postowl.git
cd postowl

Copy the deployment scripts from this example into your fork:

# Copy the clevercloud directory
cp -r /path/to/this/example/clevercloud ./clevercloud
chmod +x clevercloud/*.sh

Commit and push these files to your fork.

3. Create a Cellar S3 add-on

1. In the Clever Cloud console, create a new Cellar S3 add-on
2. Create a bucket for your Litestream backups (e.g., postowl-backups)
3. Note the credentials provided (host, key ID, key secret)

4. Set up your application on Clever Cloud

1. Log in to the Clever Cloud console
2. Click on "Create" and select "An application"
3. Choose "Node.js" as the runtime environment
4. Configure your application settings (name, region, etc.)

5. Configure Environment Variables

In your application's dashboard, go to "Environment Variables" and set:

PostOwl configuration: | Variable | Description | Example | |---|---|---| | ORIGIN | Your application's public URL | https://your-app.cleverapps.io | | ADMIN_PASSWORD | Password to access the admin | your-secure-password | | ADMIN_NAME | Display name for the admin | Your Name | | ADMIN_EMAIL | Admin email address | [email protected] | | DATABASE_URL | Path to the SQLite database | ./data/db.sqlite3 |

SMTP configuration (for email notifications): | Variable | Description | Example | |---|---|---| | SMTP_HOST | SMTP server host | smtp.example.com | | SMTP_PORT | SMTP server port | 587 | | SMTP_USER | SMTP username | your-smtp-user | | SMTP_PASS | SMTP password | your-smtp-password |

Litestream configuration: | Variable | Description | Example | |---|---|---| | LITESTREAM_VERSION | Litestream version to install | 0.3.13 | | DB_PATH | Path to the SQLite database | data/db.sqlite3 | | DATA_DIR | Directory for the database | data | | LITESTREAM_BUCKET | Cellar S3 bucket name | postowl-backups | | LITESTREAM_BACKUPS | Path inside the bucket | backups | | BUCKET_DIRECTORY | Bucket directory | backups |

The CELLAR_ADDON_HOST, CELLAR_ADDON_KEY_ID, CELLAR_ADDON_KEY_SECRET, and CELLAR_REGION variables are automatically set when you link the Cellar add-on to your application.

Clever Cloud hooks: | Variable | Value | |---|---| | CC_POST_BUILD_HOOK | ./clevercloud/post-build.sh | | CC_PRE_RUN_HOOK | ./clevercloud/pre-run.sh |

6. Deploy Your Application

You can deploy your application using Git:

# Add Clever Cloud as a remote repository
git remote add clever git+ssh://[email protected]/app_<your-app-id>.git

# Push your code to deploy
git push clever master

Option 2: Deploy using Clever Tools CLI

1. Install Clever Tools

Install the Clever Tools CLI following the official documentation:

# Using npm
npm install -g clever-tools

# Or using Homebrew (macOS)
brew install clever-tools

2. Log in to your Clever Cloud account

clever login

3. Fork, clone, and prepare PostOwl

# Clone your fork of PostOwl
git clone https://github.com/<your-username>/postowl.git
cd postowl

# Copy the deployment scripts from this example
cp -r /path/to/this/example/clevercloud ./clevercloud
chmod +x clevercloud/*.sh

# Commit the deployment scripts
git add clevercloud/
git commit -m "Add Clever Cloud deployment scripts"

4. Create a new application

# Initialize the current directory as a Clever Cloud application
clever create --type node postowl-example

5. Create and link a Cellar S3 add-on

# Create Cellar add-on
clever addon create cellar-addon postowl-example-cellar --link postowl-example

6. Configure environment variables

# PostOwl configuration
clever env set ORIGIN "https://$(clever domain | tr -d " ")"
clever env set ADMIN_PASSWORD "your-secure-password"
clever env set ADMIN_NAME "Your Name"
clever env set ADMIN_EMAIL "[email protected]"
clever env set DATABASE_URL "./data/db.sqlite3"

# SMTP configuration
clever env set SMTP_HOST "smtp.example.com"
clever env set SMTP_PORT "587"
clever env set SMTP_USER "your-smtp-user"
clever env set SMTP_PASS "your-smtp-password"

# Litestream configuration
clever env set LITESTREAM_VERSION "0.5.9"
clever env set DB_PATH "data/db.sqlite3"
clever env set DATA_DIR "data"
clever env set LITESTREAM_BUCKET "$(clever domain | tr -d " " | tr -d "/" | awk -F. '{print $1}')"
clever env set LITESTREAM_BACKUPS "backups"
clever env set BUCKET_DIRECTORY "backups"

# Clever Cloud hooks
clever env set CC_POST_BUILD_HOOK "./clevercloud/post-build.sh"
clever env set CC_PRE_RUN_HOOK "./clevercloud/pre-run.sh"

7. Deploy your application

clever deploy

8. Open your application in a browser

clever open

How Litestream Backup Works

The deployment uses Litestream to continuously replicate your SQLite database to Cellar S3:

1. After build (CC_POST_BUILD_HOOK): Litestream is downloaded, configured, and restores the latest backup from S3 (if one exists). This step is cached between deploys.
2. Before run (CC_PRE_RUN_HOOK): If no backup was restored (fresh deploy), the database is initialized from the schema. Then Litestream replication starts in the background, continuously backing up changes to S3.
3. At runtime: PostOwl starts normally via npm run start, with Litestream replicating in the background.

This ensures your data persists across deployments and restarts, even though Clever Cloud uses ephemeral file systems.

Monitoring Your Application

Once deployed, you can monitor your application through:

• Web Console: The Clever Cloud console provides logs, metrics, and other tools to help you manage your application.
• CLI: Use clever logs to view application logs and clever status to check the status of your application.

Additional Resources

• PostOwl Documentation
• SvelteKit Documentation
• Litestream Documentation
• Clever Cloud Node.js Documentation
• Clever Cloud Cellar Documentation
• Clever Cloud Documentation