diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..52f26b5 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,36 @@ +name: Deploy Docs to GitHub Pages + +on: + push: + branches: + - main + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup pnpm + uses: pnpm/action-setup@v2 + with: + version: 8 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build documentation site + run: pnpm docs:build + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/.vitepress/dist diff --git a/.gitignore b/.gitignore index 044f0f7..821d606 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,7 @@ pnpm-debug.log # Dev .dev + +# Vitepress +docs/.vitepress/dist +docs/.vitepress/cache diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 0000000..3a9f245 --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,45 @@ +import { defineConfig } from 'vitepress'; + +export default defineConfig({ + title: 'OpenArchiver Documentation', + description: 'Official documentation for the OpenArchiver project.', + themeConfig: { + nav: [ + { text: 'Home', link: '/README' }, + { text: 'User Guides', link: '/user-guides/email-providers/README' } + ], + sidebar: [ + { + text: 'User Guides', + items: [ + { text: 'Get Started', link: '/README' }, + { text: 'Installation', link: '/user-guides/installation' }, + { + text: 'Email Providers', + link: '/user-guides/email-providers/README', + collapsed: true, + items: [ + { text: 'Google Workspace', link: '/user-guides/email-providers/google-workspace' }, + { text: 'Generic IMAP Server', link: '/user-guides/email-providers/imap' }, + { text: 'Microsoft 365', link: '/user-guides/email-providers/microsoft-365' } + ] + } + ] + }, + { + text: 'API Reference', + items: [ + { text: 'Overview', link: '/api/README' }, + { text: 'Ingestion API', link: '/api/ingestion' } + ] + }, + { + text: 'Services', + items: [ + { text: 'Overview', link: '/services/README' }, + { text: 'Storage Service', link: '/services/storage-service' } + ] + } + ] + } +}); diff --git a/docs/README.md b/docs/README.md index 08d62cb..87dc4a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,2 +1,42 @@ -# Get started +# Get Started +Welcome to Open Archiver! This guide will help you get started with setting up and using the platform. + +## What is Open Archiver? + +**A secure, sovereign, and affordable open-source platform for email archiving and eDiscovery.** + +Open Archiver provides a robust, self-hosted solution for archiving, storing, indexing, and searching emails from major platforms, including Google Workspace (Gmail), Microsoft 365, as well as generic IMAP-enabled email inboxes. Use Open Archiver to keep a permanent, tamper-proof record of your communication history, free from vendor lock-in. + +## Key Features + +- **Universal Ingestion**: Connect to Google Workspace, Microsoft 365, and standard IMAP servers to perform initial bulk imports and maintain continuous, real-time synchronization. +- **Secure & Efficient Storage**: Emails are stored in the standard `.eml` format. The system uses deduplication and compression to minimize storage costs. All data is encrypted at rest. +- **Pluggable Storage Backends**: Support both local filesystem storage and S3-compatible object storage (like AWS S3 or MinIO). +- **Powerful Search & eDiscovery**: A high-performance search engine indexes the full text of emails and attachments (PDF, DOCX, etc.). +- **Compliance & Retention**: Define granular retention policies to automatically manage the lifecycle of your data. Place legal holds on communications to prevent deletion during litigation (TBD). +- **Comprehensive Auditing**: An immutable audit trail logs all system activities, ensuring you have a clear record of who accessed what and when (TBD). + +## Installation + +To get your own instance of Open Archiver running, follow our detailed installation guide: + +- [Installation Guide](./user-guides/installation.md) + +## Data Source Configuration + +After deploying the application, you will need to configure one or more ingestion sources to begin archiving emails. Follow our detailed guides to connect to your email provider: + +- [Connecting to Google Workspace](./user-guides/email-providers/google-workspace.md) +- [Connecting to Microsoft 365](./user-guides/email-providers/microsoft-365.md) +- [Connecting to a Generic IMAP Server](./user-guides/email-providers/imap.md) + +## Contributing + +We welcome contributions from the community! + +- **Reporting Bugs**: If you find a bug, please open an issue on our GitHub repository. +- **Suggesting Enhancements**: Have an idea for a new feature? We'd love to hear it. Open an issue to start the discussion. +- **Code Contributions**: If you'd like to contribute code, please fork the repository and submit a pull request. + +Please read our `CONTRIBUTING.md` file for more details on our code of conduct and the process for submitting pull requests. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index d29ff6d..290bc06 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -2,15 +2,16 @@ ## User guides -* [Get started](README.md) -* [email-providers](user-guides/email-providers/README.md) - * [Connecting to Google Workspace](user-guides/email-providers/google-workspace.md) - * [Connecting to a Generic IMAP Server](user-guides/email-providers/imap.md) - * [Connecting to Microsoft 365](user-guides/email-providers/microsoft-365.md) +- [Get started](get-started.md) +- [Installation](user-guides/installation.md) +- [email-providers](user-guides/email-providers/README.md) + - [Connecting to Google Workspace](user-guides/email-providers/google-workspace.md) + - [Connecting to a Generic IMAP Server](user-guides/email-providers/imap.md) + - [Connecting to Microsoft 365](user-guides/email-providers/microsoft-365.md) -*** +--- -* [api](api/README.md) - * [Ingestion Sources API Documentation](api/ingestion.md) -* [services](services/README.md) - * [Pluggable Storage Service (StorageService)](services/storage-service.md) +- [api](api/README.md) + - [Ingestion Sources API Documentation](api/ingestion.md) +- [services](services/README.md) + - [Pluggable Storage Service (StorageService)](services/storage-service.md) diff --git a/docs/api/README.md b/docs/api/README.md index a1df0ab..c67872c 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,2 +1 @@ -# api - +# API documentation diff --git a/docs/api/ingestion.md b/docs/api/ingestion.md index a24f91b..1046945 100644 --- a/docs/api/ingestion.md +++ b/docs/api/ingestion.md @@ -1,6 +1,6 @@ # Ingestion Sources API Documentation -A comprehensive guide to using the Ingestion Sources API. +A guide to using the Ingestion Sources API. **Base Path:** `/v1/ingestion-sources` diff --git a/docs/user-guides/installation.md b/docs/user-guides/installation.md new file mode 100644 index 0000000..f261330 --- /dev/null +++ b/docs/user-guides/installation.md @@ -0,0 +1,99 @@ +# Installation Guide + +This guide will walk you through setting up Open Archiver using Docker Compose. This is the recommended method for deploying the application. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your server or local machine. +- A server or local machine with at least 2GB of RAM. +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your server or local machine. + +## 1. Clone the Repository + +First, clone the Open Archiver repository to your machine: + +```bash +git clone https://github.com/LogicLabs-OU/OpenArchiver.git +cd OpenArchiver +``` + +## 2. Configure Your Environment + +The application is configured using environment variables. You'll need to create a `.env` file to store your configuration. + +Copy the example environment file for Docker: + +```bash +cp .env.example.docker .env +``` + +Now, open the `.env` file in a text editor and customize the settings. + +### Important Configuration + +You must change the following placeholder values to secure your instance: + +- `POSTGRES_PASSWORD`: A strong, unique password for the database. +- `REDIS_PASSWORD`: A strong, unique password for the Valkey/Redis service. +- `MEILI_MASTER_KEY`: A complex key for Meilisearch. +- `JWT_SECRET`: A long, random string for signing authentication tokens. +- `ADMIN_PASSWORD`: A strong password for the initial admin user. +- `ENCRYPTION_KEY`: A 32-byte hex string for encrypting sensitive data in the database. You can generate one with the following command: + ```bash + openssl rand -hex 32 + ``` + +### Storage Configuration + +By default, the Docker Compose setup uses local filesystem storage, which is persisted using a Docker volume named `archiver-data`. This is suitable for most use cases. + +If you want to use S3-compatible object storage, change the `STORAGE_TYPE` to `s3` and fill in your S3 credentials (`STORAGE_S3_*` variables). + +## 3. Run the Application + +Once you have configured your `.env` file, you can start all the services using Docker Compose: + +```bash +docker compose up -d +``` + +This command will: + +- Pull the required Docker images for the frontend, backend, database, and other services. +- Create and start the containers in the background (`-d` flag). +- Create the persistent volumes for your data. + +You can check the status of the running containers with: + +```bash +docker compose ps +``` + +## 4. Access the Application + +Once the services are running, you can access the Open Archiver web interface by navigating to `http://localhost:3000` in your web browser. + +You can log in with the `ADMIN_EMAIL` and `ADMIN_PASSWORD` you configured in your `.env` file. + +## 5. Next Steps + +After successfully deploying and logging into Open Archiver, the next step is to configure your ingestion sources to start archiving emails. + +- [Connecting to Google Workspace](./email-providers/google-workspace.md) +- [Connecting to Microsoft 365](./email-providers/microsoft-365.md) +- [Connecting to a Generic IMAP Server](./email-providers/imap.md) + +## Updating Your Installation + +To update your Open Archiver instance to the latest version, run the following commands: + +```bash +# Pull the latest changes from the repository +git pull + +# Pull the latest Docker images +docker compose pull + +# Restart the services with the new images +docker compose up -d +``` diff --git a/package.json b/package.json index 5eba6ce..6201fca 100644 --- a/package.json +++ b/package.json @@ -10,14 +10,18 @@ "db:generate": "dotenv -- pnpm --filter @open-archiver/backend db:generate", "db:migrate": "dotenv -- pnpm --filter @open-archiver/backend db:migrate", "db:migrate:dev": "dotenv -- pnpm --filter @open-archiver/backend db:migrate:dev", - "docker-start": "concurrently \"pnpm start:workers\" \"pnpm start\"" + "docker-start": "concurrently \"pnpm start:workers\" \"pnpm start\"", + "docs:dev": "vitepress dev docs --port 3009", + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" }, "dependencies": { "concurrently": "^9.2.0", "dotenv-cli": "8.0.0" }, "devDependencies": { - "typescript": "5.8.3" + "typescript": "5.8.3", + "vitepress": "^1.6.3" }, "packageManager": "pnpm@10.13.1", "engines": {