Ozma is an open-source CRM/ERP platform that allows for the rapid development of customizable enterprise systems. Build and tailor CRM/ERP solutions quickly and efficiently to meet your business needs.

• Low-Code Development: Accelerate your system development.
• Fully Customizable: Adaptable to any business process.
• Developer-Friendly: No expensive training required.

• Introduction
• Features
• Prerequisites
• Setup Options
  • Running in Development Environment
  • Running in Production Environment
• Accessing the Application
• Logging In
  • Ozma Admin User
  • Keycloak Admin User
• Importing Database Dumps
• Managing Users
  • Keycloak Integration
  • Restoring Users
• Updating the Application
• Stopping the Application
• FAQs
• Contributing
• License

Before you begin, ensure you have the following:

• Operating System: Ubuntu or any Linux distribution
• Root Access: Administrative privileges on your server
• Domain Name: A registered domain (e.g., your-domain.com) pointing to your server's IP address
• Docker Engine: Installed Docker CE (Community Edition)
• Git: Installed Git for cloning the repository

Install Git:

sudo apt update
sudo apt install git

Install Docker:

• Follow the official Docker installation guide for Ubuntu: Install Docker Engine on Ubuntu

You can set up Ozma in either a development environment or a production environment, depending on your needs.

Follow these steps to set up Ozma in a development environment.

If you haven't already cloned the repository, do so now:

git clone https://github.com/ozma-io/ozma.git
cd ozma

Copy the example environment file for development:

cp env.dev.example .env

Start the development server using Docker Compose:

docker compose up

This will start the development environment with all the required services.

Once the server is running, you can access the application and administrative interfaces:

• Ozma Application: https://localhost:9080/
• Keycloak Admin Interface: https://localhost:9080/auth/
• Report Generator Admin Interface: http://localhost:9080/report-generator/admin/ozma/

Use the following default credentials to log in:

Ozma Admin User

• Username: [email protected]
• Password: admin (You will be prompted to change your password upon first login)

Keycloak Admin User

• Username: admin
• Password: admin

Note: The development server runs on https://localhost:9080. Ensure that port 9080 is open and not used by other applications on your local machine.

Follow these steps to install Ozma in a production environment.

Set up a machine with Linux (Ubuntu is recommended). You can use any cloud provider such as AWS, Google Cloud, Yandex.Cloud etc.

• Register a domain name or use an existing one (e.g., your-domain.com).
• Create an A record in your DNS settings pointing your-domain.com to your server's IP address.
• If using a subdomain, ensure it also points to your server.

Update your package lists:

sudo apt update

Install Git and other dependencies:

sudo apt install git ca-certificates curl

Install Docker:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce

Clone the Ozma repository:

git clone https://github.com/ozma-io/ozma.git
cd ozma

Copy the example environment file for production:

cp env.production.example .env

Edit the .env file:

nano .env

In the .env file, you need to:

• Set a password for the Keycloak admin user by replacing KEYCLOAK_ADMIN_PASSWORD with your desired password.
• Replace example.com with your domain in CADDY_ADDRESS and EXTERNAL_ORIGIN.
• Set ADMIN_EMAIL to your admin email address.

Note: Ensure that the EXTERNAL_ORIGIN matches the domain you will use to access the application. This setting is applied only during the initial setup. If you change it later, you will need to recreate the containers (see below).

Start the application in production mode:

docker compose up -d

Wait for Docker to pull images and start the containers. This may take some time.

Once the containers are up and running, you can access the application at your domain:

• Ozma Application: https://your-domain.com/
• Keycloak Admin Interface: https://your-domain.com/auth/
• Report Generator Admin Interface: https://your-domain.com/report-generator/admin/ozma/

Note: Replace your-domain.com with your actual domain name.

After setting up either the development or production environment, you can access the application using the URLs provided.

Important: Some URLs require a trailing slash (/) at the end. Always use the URLs as specified to avoid any issues.

• Username:
  • For production: The ADMIN_EMAIL you set in your .env file.
  • For development: [email protected]
• Password: admin (You will be prompted to change your password upon first login)

• Username: admin
• Password:
  • For production: The password you set in KEYCLOAK_ADMIN_PASSWORD in your .env file.
  • For development: admin

If you have a database dump to import (e.g., for testing or restoring data), follow these steps:

You can copy the dump file to your server using scp or download it directly on the server using curl:

curl -LO 'https://your-dump-url/ozmadb.pg_dump'

If the containers are not already running, start them:

docker compose up -d

Run the following command to drop and recreate the databases:

docker compose exec -T postgres psql -U postgres <<< '
SELECT pg_terminate_backend(pg_stat_activity.pid)
FROM pg_stat_activity
WHERE pid <> pg_backend_pid() AND datname IS NOT NULL;

DROP DATABASE "ozmadb";
CREATE DATABASE "ozmadb" OWNER "ozmadb";
\c ozmadb
ALTER SCHEMA public OWNER TO "ozmadb";

DROP DATABASE "ozma-report-generator";
CREATE DATABASE "ozma-report-generator" OWNER "ozma-report-generator";
\c ozma-report-generator
ALTER SCHEMA public OWNER TO "ozma-report-generator";
'

Note: If you modify the .env file after the initial setup, you need to remove existing containers and volumes to apply the changes:

docker compose down -v
docker compose up -d

Restore the Ozma database:

docker compose exec -T postgres pg_restore -U ozmadb -d ozmadb -xO < path/to/ozmadb.pg_dump

If you are using the Report Generator, restore its database as well:

docker compose exec -T postgres pg_restore -U ozma-report-generator -d ozma-report-generator -xO < path/to/report-generator.pg_dump

After restoring the databases, you should be able to access the Ozma application at your domain and see your data.

Ozma uses Keycloak for user authentication and management. To manage users:

1. Access the Keycloak Admin Interface at https://your-domain.com/auth/
2. Log in with:

• Username: admin
• Password: The password you set in KEYCLOAK_ADMIN_PASSWORD in your .env file

If Users Authenticate via Google If your users authenticate via Google, you need to configure Google integration in Keycloak:

• Follow this guide: Signing in with Google with Keycloak

After setting up, users can log in with Google, and if their email matches an email in the public.users table in the database, they will have the same permissions as before.

If Users Do Not Use Google If users do not use Google authentication, you need to create user accounts in Keycloak manually:

Log in to Keycloak via command line:

docker compose exec keycloak /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin

Create users from the list of users in Ozma:

docker compose exec -T postgres psql -U postgres ozmadb -tA -c "SELECT email FROM users WHERE email LIKE '%@%';" | \
xargs -I{} docker compose exec keycloak /opt/keycloak/bin/kcadm.sh create users -r ozma -s username={} -s email={} -s enabled=true

Instruct your users to use the "Forgot Password" feature on the login page to set their passwords via email.

Note: Replace email with the appropriate column name from your users table if different.

To update the application to the latest version:

Pull the latest changes from the repository:

git pull

Rebuild and restart the containers:

docker compose up --build --pull always --remove-orphans -d

Warning: Be cautious when pulling the latest changes. Major updates might include breaking changes such as database upgrades. Always back up your data before updating.

To stop the application:

docker compose down

If you want to remove all data and volumes (this will delete your databases and any stored data), run:

docker compose down -v

Warning: Removing volumes will delete your databases and any persistent data.

A: Ensure you are accessing the correct URL with a trailing slash: https://your-domain.com/auth/

A: This indicates that the database is empty. You may need to import your database dump or check that the migrations have run correctly.

A: Follow the guide here: Signing in with Google with Keycloak

A: Ensure you have rebuilt the Docker images and restarted the containers using:

docker compose up --build --pull always --remove-orphans -d

Check for any breaking changes in the update notes or contact the maintainers for support.

A: Run the following command to stop the containers and remove all associated volumes:

docker compose down -v

A: Please refer to the Contributing section below.

We welcome contributions from the community. Please follow these steps:

1. Fork the repository.
2. Create a new branch with a descriptive name.
3. Make your changes and commit them with clear messages.
4. Submit a pull request to the main branch.

This project is licensed under the Apache License 2.0. You may obtain a copy of the License at LICENSE.