ConvoForge Documentation

Getting Started

Begin by making use of the Docker image or by cloning the Git repository. A postgres database should be setup as well.

Environment Variables

Environment variables configure the application, and can be setup through an .env or a docker compose file. The following variables are required (even if S3 functionality is not being used, these should not be empty):

• DATABASE_URL: The URL for connecting to the PostgreSQL database.
  Example: `postgres://username:password@hostname:5432/convoforge`
• CLIENT_SECRET: A key used by the client for secure operations.
  Example: `your-client-secret`
  Details: A secure random string for encryption or token generation.
• JWT_SECRET: A key used to sign and verify JSON Web Tokens (JWTs).
  Example: `your-jwt-secret`
  Details: This should be a strong, random string to secure JWTs.
• AWS_S3_BUCKET_NAME: The name of the AWS S3 bucket for storing files.
  Example: `your-s3-bucket-name`
  Note: Currently, only DigitalOcean Spaces is supported.
• AWS_REGION: The AWS region where your S3 bucket is located.
  Example: `us-west-2`
• AWS_ACCESS_KEY_ID: Your AWS Access Key ID for authenticating requests to AWS services.
  Example: `your-aws-access-key-id`
• AWS_SECRET_ACCESS_KEY: Your AWS Secret Access Key, used with the Access Key ID to authenticate requests.
  Example: `your-aws-secret-access-key`

Docker Compose Example:

Setup Application

To set up the application, follow the steps below:

1. Clone the repository or use the provided Docker image.
2. Ensure that a new Postgres database is set up for ConvoForge and the DATABASE_URL environment variable is correctly configured.
3. Set up your environment variables for AWS, JWT, and client secrets as mentioned above.
4. Once your environment is ready, start the application using Docker or run it manually via Cargo. Keep in mind that the application listens on port 8080.
5. To enable using S3, see the Create or Update Feature Flag endpoint.

Creating an Organization and Admin User

All channels, roles, and users are separated by organizations. In the application, organizations are created with UUIDv4 slugs, and the first step is to create an organization. You can do this by calling the backend API as shown below (Example shown is in Node.js):

const response = await fetch('https://api.yourdomain.com/auth/organization', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Client-Secret': 'YourClientSecret123'
    },
});

if (!response.ok) {
    console.error('Error creating organization');
}

const organization = await response.json();
console.log('Organization created:', organization);

Example response:

{
    "id": "c9d5b0e8-4c0a-4db5-991d-1e5f3a6c4d72",
}

Once the organization is created, the next step is to create an admin user, generate a role, and assign that role to the admin. It is worth noting that the integrating application should be calling this logic and returning a token to the user separately. Here is how to create the admin user:

const response = await fetch('https://api.yourdomain.com/auth/secret', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Client-Secret': 'YourClientSecret123'
    },
    body: JSON.stringify({
        username: "admin",
        display_name: "Administrator",
        slug: "c9d5b0e8-4c0a-4db5-991d-1e5f3a6c4d72"
    })
});

if (!response.ok) {
    console.error('Error creating admin user');
}

const { token } = await response.json();
console.log('Admin user created. Token:', token);

Now that you have the admin user, use the token to create an administrator role:

const response = await fetch('https://api.yourdomain.com/role/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Client-Secret': 'YourClientSecret123',
        'Authorization': 'Bearer your_jwt_token'
    },
    body: JSON.stringify({
        name: "Administrator",
        administrator: true,
        manage_users: true,
        manage_channels: true,
        manage_roles: true
    })
});

if (!response.ok) {
    console.error('Error creating admin role');
}

const role = await response.json();
console.log('Admin role created:', role);

Finally, assign the role to the admin user:

const response = await fetch('https://api.yourdomain.com/user-role-access/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Client-Secret': 'YourClientSecret123',
        'Authorization': 'Bearer your_jwt_token'
    },
    body: JSON.stringify({
        user_id: "c9d5b0e8-4c0a-4db5-991d-1e5f3a6c4d72",
        role_id: "e14f9093-8ef5-44d3-ae84-1b6f372b35b2"
    })
});

if (!response.ok) {
    console.error('Error assigning admin role');
}
console.log('Admin role assigned successfully');