Web GUI

Aveloxis includes a web-based GUI for managing repository groups with OAuth login. Users authenticate via GitHub or GitLab, create named groups, and add individual repositories or entire organizations/groups for collection.

Prerequisites

Before starting the web GUI you need:

1. A working Aveloxis installation with aveloxis migrate already run.

2. At least one OAuth app registered with GitHub and/or GitLab.

3. The web section filled in within your aveloxis.json config file.

Creating a GitHub OAuth App

1. Go to https://github.com/settings/developers.

2. Click New OAuth App.

3. Fill in the fields:

   • Application name: anything you like (e.g., “Aveloxis”).

   • Homepage URL: your Aveloxis web GUI URL (e.g., http://localhost:8082).

   • Authorization callback URL: http://localhost:8082/auth/github/callback (replace http://localhost:8082 with your web.base_url if different).

4. Click Register application.

5. Copy the Client ID and generate a new Client Secret. Put both in your aveloxis.json under web.github_client_id and web.github_client_secret.

Creating a GitLab OAuth App

1. Go to https://gitlab.com/-/profile/applications (or the equivalent URL on your self-hosted GitLab instance).

2. Fill in the fields:

   • Name: anything you like (e.g., “Aveloxis”).

   • Redirect URI: http://localhost:8082/auth/gitlab/callback (replace http://localhost:8082 with your web.base_url if different).

   • Scopes: check read_user.

3. Click Save application.

4. Copy the Application ID and Secret. Put both in your aveloxis.json under web.gitlab_client_id and web.gitlab_client_secret.

5. If using a self-hosted GitLab instance, set web.gitlab_base_url to your instance URL (e.g., https://gitlab.example.com). The default is https://gitlab.com.

Configuration

Important

Local development: Set "dev_mode": true in the "web" section below if you are running over plain HTTP (e.g., http://localhost:8082). Without this, session cookies are marked Secure and your browser will not send them over HTTP, causing login to fail silently.

All web GUI settings live under the web key in aveloxis.json:

{
  "web": {
    "addr": ":8082",
    "base_url": "http://localhost:8082",
    "session_secret": "change-me-to-a-random-string",
    "dev_mode": false,
    "github_client_id": "Iv1.abc123...",
    "github_client_secret": "deadbeef...",
    "gitlab_client_id": "your-gitlab-app-id",
    "gitlab_client_secret": "your-gitlab-app-secret",
    "gitlab_base_url": "https://gitlab.com"
  }
}

Field	Description	Default
web.addr	Listen address for the web server	":8082"
web.base_url	External URL used to construct OAuth callback URLs	"http://localhost:8082"
web.session_secret	Secret key for signing session cookies. Use a long random string.	(required)
web.dev_mode	Set true for local HTTP development. Disables the Secure flag on cookies so they work without HTTPS. Do not enable in production. HttpOnly is always set regardless.	false
web.github_client_id	Client ID from your GitHub OAuth app	""
web.github_client_secret	Client secret from your GitHub OAuth app	""
web.gitlab_client_id	Application ID from your GitLab OAuth app	""
web.gitlab_client_secret	Secret from your GitLab OAuth app	""
web.gitlab_base_url	Base URL for the GitLab instance (for self-hosted)	"https://gitlab.com"

You only need to configure the providers you want to use. If you only use GitHub, you can leave the GitLab fields empty (and vice versa). The login page will only show buttons for configured providers.

Starting the Web GUI

aveloxis web

The server starts on the address specified by web.addr (default :8082). Open http://localhost:8082 in your browser.

Login Flow

1. On the home page, click Login with GitHub or Login with GitLab.

2. You are redirected to the provider’s authorization page. Approve access for the Aveloxis OAuth app.

3. The provider redirects back to Aveloxis with an authorization code.

4. Aveloxis exchanges the code for an access token and fetches your profile (login, email, avatar).

5. A session cookie is set in your browser. You are now logged in and redirected to the dashboard.

Creating Groups

Groups are named collections of repositories. After logging in:

1. Click New Group on the dashboard.

2. Enter a group name and optional description.

3. Click Create. The empty group appears on your dashboard.

Adding Individual Repos to a Group

1. Open a group from the dashboard.

2. Click Add Repository.

3. Paste the repository URL (e.g., https://github.com/chaoss/augur or https://gitlab.com/fdroid/fdroidclient).

4. Click Add. The repo is added to the group and automatically queued for collection.

Platform is auto-detected from the URL, the same as aveloxis add-repo.

Adding an Entire GitHub Org or GitLab Group

1. Open a group from the dashboard.

2. Click Add Organization.

3. Paste the org URL (e.g., https://github.com/chaoss or https://gitlab.com/gnome).

4. Click Add. All current repositories in the org are added to the group and queued.

Behind the scenes, a row is inserted into the user_org_requests table to track the org for ongoing discovery.

Navigation and Breadcrumbs

The web GUI uses breadcrumb navigation across the top of every page:

• Dashboard: Shows Home as the breadcrumb. Lists all your groups with repo counts.

• Group detail page: Shows Home / {Group Name}. Click Home to return to the dashboard.

Comparing Repositories

Each group detail page (and the main dashboard) includes a Compare Repositories search widget. This uses the REST API (aveloxis api) to search across all repositories in the database — not just those in the current group. Select up to 5 repos, click Compare, and you are taken to the comparison page with your selection pre-populated.

The API must be running (aveloxis api --addr :8383) for the compare search to work.

Searching and Pagination

Groups that track organizations can accumulate hundreds or thousands of repositories. The group detail page provides search and pagination to make large lists manageable.

Search

At the top of the repository list, a search box lets you filter by name. The search is case-insensitive and matches against the repository name, owner, and full URL. For example, searching augur will match chaoss/augur, chaoss/augur-community-reports, etc.

Click Clear next to the search box to remove the filter and return to the full list. The result count updates to show how many repositories match your query.

Pagination

Repositories are displayed 25 per page. When a group has more than 25 repos, pagination controls appear at the bottom of the table:

• First / Last links to jump to the beginning or end.

• Previous / Next links to move one page at a time.

• A sliding window of 5 page numbers centered on the current page, so the controls stay compact even with hundreds of pages.

• The current page number is highlighted.

Search and pagination work together: if you search for chaoss and there are 40 matches, you see 25 on page 1 and 15 on page 2. The search query is preserved as you navigate between pages.

How Org Tracking Works

When you add an org, Aveloxis does not just snapshot the current repo list – it continuously monitors the org for new repos:

• A scheduler task runs every 4 hours and re-fetches the repository list for every org in user_org_requests.

• Any newly created repos that are not already in the database are added to the group and queued for collection automatically.

• Repos that are deleted or made private on the forge are handled by the existing dead repo sidelining logic during collection.

This means you can add https://github.com/kubernetes once and Aveloxis will automatically pick up new repos as the Kubernetes org creates them.

How Repos Get Queued for Collection

Repos added through the web GUI (individually or via org tracking) are inserted into the same aveloxis_ops.collection_queue used by the CLI. They are collected by aveloxis serve in priority order, just like repos added via aveloxis add-repo.

You must have aveloxis serve running for collection to happen. The web GUI only manages the queue – it does not collect data itself.

Session Management

• Sessions are stored in-memory on the web server process.

• Each session expires after 24 hours of inactivity.

• Restarting aveloxis web clears all sessions. Users will need to log in again.

• Sessions are tied to a secure, signed cookie. The signing key is web.session_secret from your config.

Running Alongside aveloxis serve

The web GUI and the collection scheduler are separate processes. In a typical deployment you run both:

# Terminal 1: collection scheduler with monitoring dashboard
aveloxis serve --workers 4 --monitor :5555

# Terminal 2: web GUI for group management
aveloxis web

They share the same PostgreSQL database. The web GUI writes to the queue; the scheduler reads from it. There is no direct communication between the two processes.

You can run them on different hosts as long as both can reach the database.

Security Considerations

• OAuth tokens: The access tokens obtained during login are used only to fetch the user’s profile and are not stored persistently. They are held in the session for the duration of the login.

• Session cookies: Signed with web.session_secret. Use a strong, random secret in production. If the secret is compromised, an attacker could forge session cookies. All cookies set HttpOnly to prevent JavaScript access. The Secure flag is set in production (default) but can be disabled for local HTTP development via "dev_mode": true.

• HTTPS: In production, run aveloxis web behind a reverse proxy (nginx, Caddy, etc.) that terminates TLS. OAuth providers require HTTPS callback URLs for production apps (localhost is exempt during development). Leave dev_mode at its default (false) in production — this ensures cookies are only sent over HTTPS.

• Development mode: For local development over plain HTTP, set "dev_mode": true in the web section of aveloxis.json. This disables the Secure cookie flag so session cookies work without HTTPS. HttpOnly remains enabled even in dev mode. Never deploy with dev_mode enabled.

• Client secrets: The web.github_client_secret and web.gitlab_client_secret values in aveloxis.json are sensitive. Protect the config file with appropriate file permissions (chmod 600 aveloxis.json).

• No role-based access control: Currently all authenticated users have the same permissions. Any logged-in user can create groups and add repos. If you need to restrict access, control who can reach the web GUI at the network level.