Obsidian Publish is a powerful self-hosted platform for publishing Markdown-based knowledge repositories directly from your Obsidian vaults. It offers unmatched flexibility, complete control over your data, and the ability to customize and extend functionality to meet your specific needs. In this guide, weβll cover the full lifecycle of deploying, configuring, managing, and leveraging Obsidian Publishβfrom setup and reverse proxy configuration to logging, backups, updates, and advanced feature usage.
Installing Obsidian Publish
π¦ Docker/Docker Compose Setup
Using Docker is the most efficient way to deploy Obsidian Publish, ensuring a consistent and portable environment.
- Create a
docker-compose.yml
file tailored for Obsidian Publish:
version: '3.8'
services:
obsidian-publish:
image: obsidian/publish:latest
container_name: obsidian_publish
ports:
- "8080:8080" # Map host port 8080 to container port 8080
volumes:
- ./obsidian_data:/data # Persist Obsidian Publish data locally
- ./obsidian_config:/config # Persist configuration files
environment:
- TZ=UTC # Adjust the timezone as needed
- AUTH_TOKEN=your_secure_auth_token # Set a secure authentication token
restart: unless-stopped
- Deploy the container using Docker Compose:
docker-compose up -d
- Verify that the container is running:
docker ps | grep obsidian_publish
π Manual Installation
For a manual installation on a Linux server, follow these steps:
- Install required dependencies:
sudo apt update && sudo apt install -y git curl nginx
- Clone the Obsidian Publish repository (or download binaries if available):
git clone https://github.com/obsidianmd/obsidian-publish.git
cd obsidian-publish
- Start the application:
npm install # Install dependencies
npm start # Start the server
- Ensure the application is running by visiting
http://<your-server-ip>:8080
.
Configuring Nginx as a Reverse Proxy
π Nginx Configuration
Nginx allows you to serve Obsidian Publish under a custom domain and handle incoming traffic efficiently.
- Create an Nginx server block for Obsidian Publish:
sudo nano /etc/nginx/sites-available/obsidian_publish
- Add the following configuration:
server {
server_name yourdomain.com; # Replace with your domain
location / {
proxy_pass http://localhost:8080; # Obsidian Publish backend
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
- Enable the configuration and reload Nginx:
sudo ln -s /etc/nginx/sites-available/obsidian_publish /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
π SSL/TLS Setup
Secure your site with Let's Encrypt and automate certificate renewals.
- Install Certbot:
sudo apt install -y certbot python3-certbot-nginx
- Obtain and configure an SSL certificate:
sudo certbot --nginx -d yourdomain.com
- Automate renewals:
sudo systemctl enable certbot.timer
π οΈ Testing and Reloading Nginx
After configuring Nginx and SSL, verify your setup:
sudo nginx -t
sudo systemctl reload nginx
curl -IL https://yourdomain.com
Logging and Debugging Obsidian Publish
ποΈ Enabling Debug Logs
To enable debug-level logging, modify the environment configuration:
environment:
- LOG_LEVEL=debug # Adjust the log level in Docker Compose or env file
Restart the container to apply changes:
docker-compose restart
π Viewing Logs
Access logs to monitor or troubleshoot issues:
docker logs obsidian_publish
π οΈ Troubleshooting Common Issues
If you encounter errors:
-
Check the logs for specific messages.
-
Validate your
docker-compose.yml
and reverse proxy configurations. -
Ensure your authentication token or environment variables are correct.
π€ Exporting Logs
Export logs to an external monitoring system like ELK Stack:
- Install Filebeat to ship logs:
sudo apt install filebeat
- Configure the filebeat input to monitor Obsidian logs in
/var/log
or Docker logs.
Backup and Restore
ποΈ File-Based Backups
Create a snapshot of Obsidian Publishβs data directory:
tar -czvf obsidian_backup_$(date +%F).tar.gz ./obsidian_data
π Database Backups
If Obsidian Publish uses a database, back it up using:
docker exec obsidian_publish_db pg_dumpall -c -U postgres > db_backup.sql
π Automated Backup Scripts
Set up a cron job for periodic backups:
crontab -e
Add the following line:
0 0 * * * tar -czvf /backups/obsidian_backup_$(date +\%F).tar.gz /path/to/data
Updating and Upgrading Obsidian Publish
β¬οΈ Updating Docker Images
Update to the latest version of Obsidian Publish:
docker-compose pull
docker-compose up -d
π οΈ Manual Updates
For manual installations, pull the latest code:
cd obsidian-publish
git pull origin main
npm install
npm restart
π Checking for Updates
Monitor the Obsidian Publish documentation or repository for announcements about new releases.
Leveraging Obsidian Publishβs Unique Features
π§ Enabling APIs
Enable and test API functionality with the following steps:
- Add the API key to the configuration file or environment variables:
environment:
- API_KEY=your_api_key
- Test the API using
curl
:
curl -H "Authorization: Bearer your_api_key" http://localhost:8080/api/endpoint
π Advanced Configurations
Customize Obsidian Publish with advanced configurations, such as:
- Custom themes:
- Place your CSS files in the
/config/themes
directory.
- Integrate with third-party tools like Git for version control:
git init /path/to/obsidian_data
git remote add origin https://github.com/your-repo.git
git push -u origin main
Wrapping Up
This guide has walked you through the complete process of deploying, configuring, and managing Obsidian Publish. By self-hosting, you gain unparalleled control over your data and the flexibility to customize it to fit your needs. Start implementing these steps today to unlock the full potential of Obsidian Publish for your personal or professional projects!