Installing DocrepoX is straightforward, with multiple installation methods available. The simplest and most recommended approach is using a containerized installation via Docker.

Prerequisites: Installing Docker

Before proceeding, ensure Docker is installed and running on your target system. Follow the appropriate guide based on your operating system:

- Mac: https://docs.docker.com/desktop/setup/install/mac-install/
- Linux (Ubuntu/Debian-based): https://docs.docker.com/desktop/setup/install/linux/
- Windows: https://docs.docker.com/desktop/setup/install/windows-install/

Windows Users: Be sure to review the installation guide above, as there are several important caveats specific to Windows setups.

Installing DocrepoX on Linux

In this guide, I'll walk you through installing DocrepoX on a Linux system that already has Docker installed, configured, and running.

To install and start DocrepoX on your local machine, simply run the following command:

curl -s https://raw.githubusercontent.com/documendous/docrepox/main/setup.sh | bash -s -- localhost

This will download and execute the setup script, automatically configuring DocrepoX within a container.

When running the installation command, you should see output similar to this:

=== Cloning DocrepoX repository ===  
Cloning into 'docrepox'...  
remote: Enumerating objects: 1527, done.  
remote: Counting objects: 100% (1527/1527), done.  
remote: Compressing objects: 100% (905/905), done.  
remote: Total 1527 (delta 653), reused 1391 (delta 519), pack-reused 0 (from 0)  
Receiving objects: 100% (1527/1527), 5.40 MiB | 6.34 MiB/s, done.  
Resolving deltas: 100% (653/653), done.  

=== Repository cloned successfully ===  
=== Navigating to DocrepoX directory ===  
=== In DocrepoX directory ===  
=== Processing hostname for DJANGO_ALLOWED_HOSTS ===  
=== localhost is already in DJANGO_ALLOWED_HOSTS. No changes made ===  
=== Setting up Python environment ===  
=== Python environment set up successfully ===  
=== Installing dependencies ===  
Collecting poetry  
  Downloading poetry-2.1.1-py3-none-any.whl (277 kB)  
...

Once complete, you should have a docrepox folder and a running DocrepoX container.

Alternative Manual Installation

If you’re unable to run the installation in an interactive shell, the script may fail. No worries—you can set it up manually with the following steps:

1. Navigate to the docrepox directory:

cd docrepox

2. Set up a Python virtual environment:

python -m venv .venv
source .venv/bin/activate

3. Install dependencies with Poetry:

pip install poetry
poetry install
poetry run pip freeze > requirements.txt
cp requirements.txt docrepo/requirements.txt

4. Configure environment variables:

cp env.prod.example .env.prod
cp env.prod.db.example .env.prod.db
cp .env.prod docrepo/.env.prod

5. Create necessary directories:

mkdir docrepo/mediafiles

6. Start the container:

docker compose -f docker-compose.prod.yml up

First-Time Installation Considerations

The first time you run the installation, it may take a few minutes as several dependencies need to be installed. One of the larger components is a Java SDK with LibreOffice, which is included to support document transformations. Despite this, the overall installation process remains relatively lightweight and should complete within a few minutes.

On subsequent runs of `docker compose up`, the startup time will be significantly faster since all necessary components will already be installed.

Accessing DocrepoX

Once the installation is complete, open your browser and go to http://localhost

Log in using the default credentials:
- Username: `admin`
- Password: `admin`

Exploring the Dashboard

After logging in, you’ll be redirected to the dashboard, where you will see:
- A detailed description of DocrepoX
- Links to bundled documentation
- A list of available projects and documents

Since this is a fresh installation, there won’t be any projects or documents yet. If you're setting up DocrepoX for development purposes, you can choose a development installation mode, which will automatically generate a few test projects for you.

Securing Your Installation

If everything has installed correctly, you now have a working instance of DocrepoX that can function in a production environment. However, for security purposes, you must change the default admin password.

Changing the Admin Password

1. Click on Admin Console in the upper-right corner (it appears in red when logged in as `admin`).
2. Navigate to Authentication and Authorization > Users
3. Create a new user with secure credentials
4. Log out and log back in using the new user credentials

Installing DocrepoX in Development Mode

If you plan to develop on DocrepoX, follow these steps to set up a development environment.

1. Clone the Repository

Run the following commands:

git clone https://github.com/documendous/docrepox.git
cd docrepox

*If you don’t have a GitHub account, you can alternatively download and extract the repository’s ZIP file.*
*(However, I highly recommend creating a GitHub account if you don’t already have one.)*

2. Create a Virtual Environment (Python 3.10+)

python -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install poetry
poetry install

4. Generate a Requirements File

poetry export --with dev -f requirements.txt --output requirements.txt
cp requirements.txt docrepo/requirements.txt

5. Configure Environment Variables

cp env.dev.example .env.dev
cp .env.dev docrepo/.env

6. Create the mediafiles Folder

mkdir docrepo/mediafiles

7. Run Docker Compose

docker compose up --build

Accessing DocrepoX

Once running, open your browser and go to:

http://localhost:8000

Log in using:
- Username: `admin`
- Password: `admin`

Development Resources

If you’re working on DocrepoX development, check out these sections in the documentation:

- http://localhost:8000/ddocs/customizing-docrepox
- http://localhost:8000/ddocs/developing-documendous

Need Help?

If you run into issues and can’t find answers in the documentation, feel free to open an issue on GitHub:

a href="https://github.com/documendous/docrepox/issues">https://github.com/documendous/docrepox/issues

Happy coding!