Self-Hosting

This guide covers setting up and running Wraft on your own infrastructure for complete control over your document management system.

Prerequisites

Before building Wraft, ensure you have all the following dependencies installed:

Core Dependencies

  • Elixir 1.18.4
  • Erlang/OTP 27.0.1
  • PostgreSQL (latest stable version)
  • MinIO - S3 compatible object storage
  • Pandoc 3.6.3 - Document conversion engine
  • ImageMagick - Image processing
  • LaTeX - PDF generation and typography
  • Typst 0.13.0 - Modern typesetting system
  • Java 17 - For PDF signing functionality
  • Rust toolchain - For native dependencies

The exact versions are defined in the .tool-versions file in the repository.

Development Setup

1. Clone the Repository

git clone https://github.com/wraft/wraft.git
cd wraft

2. Elixir & Erlang Setup

Since these are defined in .tool-versions, asdf will install the correct versions:

First, install asdf version manager.

Add the required plugins:

asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git

Install the versions:

asdf install

⚠️ For Ubuntu users: You also need to install the inotify-tools package.

macOS:

brew install inotify-tools

Linux:

sudo apt install inotify-tools

3. PostgreSQL Setup

Select your OS from the PostgreSQL downloads page and follow the installation instructions.

Verify installation:

postgres -V

Test connectivity:

psql -h 127.0.0.1 -p 5432 -U postgres postgres

4. MinIO Setup

Download the latest version of MinIO from here and follow the OS-specific installation instructions.

Start a local MinIO instance:

minio server ~/minio --console-address :9001

Access the MinIO Console at http://127.0.0.1:9000

5. Pandoc Installation

macOS:

brew install pandoc

Linux:

  • Download the appropriate package from Pandoc releases
  • Install the deb package:
sudo dpkg -i $DEB

where $DEB is the path to the downloaded deb file.

6. ImageMagick Installation

Download ImageMagick from here for your OS.

Linux:

sudo apt update
sudo apt install imagemagick

7. LaTeX Installation

macOS: Install MacTeX distribution from here. Choose the version that supports your device.

Linux: Install Tex Live distribution:

sudo apt-get install texlive-full

For a LaTeX editor:

sudo apt-get install texmaker

8. Typst Installation

Install Typst 0.13.0 for modern typesetting capabilities:

macOS:

brew install typst

Linux: Download from Typst releases and install manually.

9. Java 17 Installation

macOS:

brew install openjdk@17

Linux:

sudo apt install openjdk-17-jdk

10. Rust Toolchain

Install Rust for native dependencies:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

11. Typesense Setup

Typesense is a fast, typo-tolerant search engine used by Wraft for search functionality.

For detailed installation instructions, refer to the official Typesense documentation.

Download from Typesense releases or run manually:

mkdir -p ~/typesense-data
typesense-server --data-dir ~/typesense-data --api-key=your-api-key-here

Note: Replace your-api-key-here with a secure API key. Default port is 8108.

Application Setup

Environment Configuration

  1. Load environment variables

    mv .env.example .env.dev
source .env.dev

  2. Setup the project

    mix setup

Running Wraft

Start Phoenix endpoint with interactive shell:

iex -S mix phx.server

Start without interactive shell:

source .env.dev && mix phx.server

Visit localhost:4000 from your browser.

API documentation is available at http://localhost:4000/api/swagger/index.html#/.

Frontend Setup

Clone the frontend repository separately:

cd ..
git clone https://github.com/wraft/wraft-frontend.git
cd wraft-frontend

Refer to the README.md in the frontend repository for setup instructions.

Default User

The default username and password:

username: wraftuser@gmail.com
password: demo@1234

Customization

Environment Configuration

Wraft uses environment variables for configuration. Key configuration options include:

  • Database connection settings
  • MinIO/S3 storage configuration
  • Application secrets and keys
  • External service integrations
  • Typesense search configuration

Database Migrations

To run database migrations:

mix ecto.migrate

To rollback migrations:

mix ecto.rollback

Asset Compilation

For production builds, compile assets:

mix assets.deploy

Development Workflow

Interactive Development

Start the development server with an interactive shell:

iex -S mix phx.server

Hot Reloading

Wraft supports hot reloading during development. Changes to Elixir files will automatically reload the server.

Debugging

Use the interactive shell for debugging:

# In the IEx shell
iex> Wraft.Repo.all(Wraft.Documents.Document)

Production Build

For production deployment:

  1. Set production environment

    export MIX_ENV=prod

  2. Install production dependencies

    mix deps.get --only prod

  3. Compile for production

    mix compile

  4. Run database migrations

    mix ecto.migrate

  5. Start the production server

    mix phx.server

Troubleshooting

Common Issues

  • Database connection errors: Ensure PostgreSQL is running and accessible
  • MinIO connection issues: Verify MinIO server is running on the correct port
  • Missing dependencies: Run mix deps.get to install all dependencies
  • Permission errors: Ensure proper file permissions for the application directory
  • Typesense connection: Verify Typesense server is running and API key is correct
  • Java/PDF signing issues: Ensure Java 17 is properly installed and accessible
  • Rust compilation errors: Update Rust toolchain and rebuild native dependencies

Getting Help

Previous

Overview

Next

Docker Compose

On this page