docuseal/README_LOCAL_SETUP.md

DocuSeal Local Development Setup

This guide will help you set up DocuSeal locally for development and testing purposes.

Prerequisites

Before you begin, make sure you have the following installed on your system:

Required Software

• Ruby 3.4.2 - Use your preferred Ruby version manager (rbenv, rvm, asdf, etc.)
• Node.js 18 - Required for frontend assets compilation
• Yarn - Package manager for Node.js dependencies
• PostgreSQL (optional) - For production-like database setup
• Redis - For background job processing (Sidekiq)

macOS Dependencies

• Homebrew - For installing system dependencies
• VIPS - For image processing
• LibreOffice (optional) - For document conversion if you encounter upload errors

Installation Steps

1. Clone the Repository

git clone https://github.com/CareerPlug/docuseal.git
cd docuseal

2. Install Ruby Dependencies

Make sure you're using Ruby 3.4.2:

# If using rbenv
rbenv install 3.4.2
rbenv local 3.4.2

# If using rvm
rvm install 3.4.2
rvm use 3.4.2

# If using asdf
asdf install ruby 3.4.2
asdf local ruby 3.4.2

Install Ruby gems:

bundle install

3. Install System Dependencies

macOS

# Install VIPS for image processing
brew install vips

# Install LibreOffice (optional, for document conversion)
brew install --cask libreoffice

4. Setup Database

The application uses SQLite by default for development. Create and migrate the database:

rails db:create db:migrate

If you prefer to use PostgreSQL for a more production-like setup:

1. Install PostgreSQL
2. Create a database
3. Update config/database.yml to use PostgreSQL for development
4. Run the migration commands

5. Install Node.js Dependencies

Make sure you're using Node.js 18:

# Check your Node version
node --version

# If you need to switch to Node 18, use your preferred version manager
# Example with nvm:
nvm install 18
nvm use 18

# Install dependencies
yarn install

6. Start the Development Servers

In separate terminal windows:

# Terminal 1: Rails server
PORT=3001 bundle exec rails s -p 3001

# Terminal 2: Webpack dev server
bundle exec ./bin/shakapacker-dev-server

7. Access the Application

Open your browser and navigate to:

• DocuSeal: http://localhost:3001

Initial Setup

1. Create Admin Account

1. Go to http://localhost:3001
2. You'll be prompted to create the first admin account
3. Fill in the required information to set up your admin user

2. Upload a Document

1. Log in with your admin account
2. Click "New Form" or "Upload Document"
3. Upload a PDF document to test the system
4. If you encounter upload errors, make sure LibreOffice is installed

Troubleshooting

Common Issues

Node.js Version Issues

If you get errors during yarn install, ensure you're using Node.js 18:

node --version  # Should show v18.x.x

Image Processing Errors

If you encounter VIPS-related errors:

# macOS
brew install vips

Document Upload Issues

If document uploads fail, install LibreOffice:

# macOS
brew install --cask libreoffice

Database Issues

If you encounter database connection issues:

# Reset the database
rails db:drop db:create db:migrate

Notes

This is a standalone DocuSeal instance, this is to more easily make customizations to the fork itself without needing to integrate with another application.

• The application runs on port 3001 by default
• All data is stored locally in SQLite database for development
• File uploads are stored in the attachments/ directory
• This setup is for local development only.