feat: Initial project setup with Wiki.js and management scripts

- Add Docker Compose setup for Wiki.js and PostgreSQL. - Include setup and backup scripts for easy management. - Create command-line scripts to create and edit wiki pages via the GraphQL API. - Add comprehensive README and .gitignore.
2025-09-08 02:22:20 +01:00
parent a2adb89d93
commit d7b0f6fee0
6 changed files with 329 additions and 140 deletions
--- a/README.md
+++ b/README.md
@@ -1,155 +1,103 @@
-# Personal Wiki.js Setup for Home Server
+# Personal Wiki.js Project

-This repository contains everything you need to set up your personal Wiki.js instance on your home server.
+This repository contains everything needed to set up, manage, and programmatically interact with a personal Wiki.js instance using Docker and Python scripts.

 ## 🚀 Quick Start

-1. **Run the setup script:**
-   ```bash
-   ./setup.sh
-   ```
+1.  **Set Up Environment**: Ensure you have `docker` and `docker-compose` installed. The `setup.sh` script will check for these.

-2. **Access your wiki:**
-   - Open http://localhost:3000 in your browser
-   - Complete the initial setup wizard
-   - Create your administrator account
+2.  **Run Setup Script**: This script generates a secure database password, creates necessary directories, and starts the wiki.
+    ```bash
+    ./setup.sh
+    ```
+
+3.  **Access Your Wiki**: Open your browser and navigate to the URL specified in your `.env` file (e.g., `http://localhost:3000` or `https://wiki.liveaodh.com`). Complete the initial setup wizard and create your administrator account.

 ## 📁 Project Structure

 ```
 wikiaodh/
 ├── docker-compose.yml    # Docker services configuration
-├── .env                  # Environment variables (passwords, etc.)
-├── setup.sh             # Automated setup script
-├── README.md            # This file
-└── data/                # Created automatically for persistent data
-    ├── wiki/            # Wiki application data
-    ├── db/              # PostgreSQL database files
-    └── assets/          # Uploaded media and assets
+├── .env                  # Environment variables (passwords, API key, etc.)
+├── setup.sh              # Automated setup script
+├── backup.sh             # Backup script for database and assets
+├── README.md             # This file
+├── requirements.txt      # Python dependencies for scripts
+├── venv/                 # Python virtual environment
+└── scripts/
+    ├── create_page.py    # CLI tool to create new wiki pages
+    └── edit_page.py      # CLI tool to edit existing wiki pages
 ```

-## 🔧 Configuration
+## 🔧 Wiki Management

-### Environment Variables (.env)
- `DB_PASSWORD`: Secure password for PostgreSQL database
- `WIKI_URL`: The URL where your wiki will be accessible
- `TZ`: Your timezone (default: Europe/London)
+### Docker Commands

-### Ports
- **3000**: Wiki.js web interface (http://localhost:3000)
- **5432**: PostgreSQL database (internal only)
+-   **Start the wiki**: `docker-compose up -d`
+-   **Stop the wiki**: `docker-compose down`
+-   **View logs**: `docker-compose logs -f`
+-   **Restart services**: `docker-compose restart`
+-   **Update to latest version**: `docker-compose pull && docker-compose up -d`

-## 📋 Management Commands
+### Backup and Restore

+-   **Run a full backup**: The `backup.sh` script creates a timestamped backup of your database and assets in the `backups/` directory.
+    ```bash
+    ./backup.sh
+    ```
+
+## 🤖 Command-Line Scripts
+
+These scripts use the Wiki.js GraphQL API to manage content programmatically. They require a Python virtual environment and an API key.
+
+### Setup
+
+1.  **Activate Virtual Environment**:
+    ```bash
+    source venv/bin/activate
+    ```
+
+2.  **Set API Key**: Generate an API key in the Wiki.js **Administration -> API Access** area and add it to your `.env` file:
+    ```
+    WIKI_API_KEY=your_api_key_here
+    ```
+
+### `scripts/create_page.py`
+
+Creates a new page in your wiki.
+
+**Usage**:
 ```bash
-# Start the wiki
-docker-compose up -d
-
-# Stop the wiki
-docker-compose down
-
-# View logs
-docker-compose logs -f
-
-# Restart services
-docker-compose restart
-
-# Update to latest version
-docker-compose pull
-docker-compose up -d
+python3 scripts/create_page.py --path "my-folder/my-new-page" --title "My New Page" --content-file "path/to/my-content.md"
 ```

-## 💾 Backup & Restore
+**Arguments**:
+-   `--path` (required): The URL path for the new page.
+-   `--title` (required): The title of the page.
+-   `--content-file` (required): Path to a markdown file with the page content.
+-   `--tags` (optional): A list of tags (e.g., `--tags project guide`).

-### Backup
+### `scripts/edit_page.py`
+
+Edits an existing page in your wiki.
+
+**Usage**:
 ```bash
-# Backup database
-docker-compose exec db pg_dump -U wikijs wiki > backup_$(date +%Y%m%d).sql
+# Update content
+python3 scripts/edit_page.py --path "home" --content-file "new_content.md"

-# Backup uploaded files
-tar -czf assets_backup_$(date +%Y%m%d).tar.gz data/assets/
+# Update title
+python3 scripts/edit_page.py --path "home" --title "New Home Page Title"
+
+# Update both
+python3 scripts/edit_page.py --path "home" --title "New Title" --content-file "new_content.md"
 ```

-### Restore
-```bash
-# Restore database
-docker-compose exec -T db psql -U wikijs wiki < backup_YYYYMMDD.sql
-
-# Restore uploaded files
-tar -xzf assets_backup_YYYYMMDD.tar.gz
-```
-
-## 🔒 Security Considerations
-
-1. **Change default passwords**: The setup script generates a secure database password automatically
-2. **Firewall**: Consider restricting access to port 3000 to your local network only
-3. **HTTPS**: For production use, set up a reverse proxy with SSL/TLS
-4. **Regular updates**: Keep Docker images updated with `docker-compose pull`
-
-## 🌐 Accessing from Other Devices
-
-To access your wiki from other devices on your network:
-
-1. Find your server's IP address: `ip addr show`
-2. Update the `WIKI_URL` in `.env` to use your server's IP
-3. Access via `http://YOUR_SERVER_IP:3000`
-
-## 📚 Wiki.js Features
-
-Your personal wiki includes:
-
- **Rich Text Editor**: WYSIWYG and Markdown support
- **Media Management**: Upload and organize images, documents, videos
- **Search**: Full-text search across all content
- **User Management**: Create accounts for family members or team
- **Themes**: Light and dark mode support
- **Mobile Friendly**: Responsive design for all devices
- **Version History**: Track changes to all pages
- **Categories & Tags**: Organize content efficiently
-
-## 🆘 Troubleshooting
-
-### Wiki won't start
-```bash
-# Check logs
-docker-compose logs
-
-# Restart services
-docker-compose down
-docker-compose up -d
-```
-
-### Database connection issues
-```bash
-# Reset database
-docker-compose down
-docker volume rm wikiaodh_db-data
-docker-compose up -d
-```
-
-### Permission issues
-```bash
-# Fix permissions
-sudo chown -R $USER:$USER data/
-chmod -R 755 data/
-```
-
-## 🔄 Updates
-
-To update Wiki.js to the latest version:
-
-```bash
-docker-compose down
-docker-compose pull
-docker-compose up -d
-```
-
-## 📞 Support
-
- [Wiki.js Documentation](https://docs.js.wiki/)
- [Wiki.js GitHub](https://github.com/Requarks/wiki)
- [Docker Compose Documentation](https://docs.docker.com/compose/)
+**Arguments**:
+-   `--path` (required): The path of the page to edit.
+-   `--content-file` (optional): Path to a markdown file with the new content.
+-   `--title` (optional): A new title for the page.

 ---

-**Enjoy your personal wiki! 📖✨**
+**Enjoy your powerful, scriptable personal wiki! 📖✨**