Document how to delete extensions from the private registry

[svor]

Currently, it’s difficult to understand how to delete extensions from the private OpenVSX registry without digging into the codebase. The existing documentation does not explain how to delete extensions, which makes the process unclear. It would be helpful to have this properly documented. Since I don’t have permission to contribute to the wiki, I’m sharing the documentation here. Could you please review it and, if appropriate, refine it and add it to the wiki?

Delete Extensions in a Private OpenVSX Registry

This guide explains how to delete extensions from a self-hosted, private OpenVSX registry that uses a PostgreSQL database. This is an administrative action that requires direct access to the registry's API and database.

Warning: Deleting an extension or its versions is an irreversible action. Please proceed with caution.

Prerequisites

Deleting extensions is a protected operation that requires a user with the admin role. By default, such a user may not exist. You must first create an administrative user and a Personal Access Token (PAT) for that user.

This is done by directly modifying the PostgreSQL database.

Step 1: Connect to Your PostgreSQL Database

Connect to the PostgreSQL database instance used by your OpenVSX registry. The connection details (host, port, username, password) will depend on your specific deployment environment.

Step 2: Create the Admin User and Token

Once connected, run the following SQL commands. We will create a new user named openvsx-admin.

1. Create the admin user:
   This command creates a new user and assigns it the necessary admin role.

   INSERT INTO user_data (id, login_name, role) VALUES (1002, 'openvsx-admin', 'admin');

   (Note: We use an id of 1002 assuming other users exist. If this ID is taken, choose another unique number.)

2. Create a Personal Access Token (PAT):
   This token will be used to authenticate with the API.

   Important: Replace your-new-secure-admin-token-here with a strong, unique token that you generate yourself.

   INSERT INTO personal_access_token (id, user_data, value, active, created_timestamp, accessed_timestamp, description) VALUES (1002, 1002, 'your-new-secure-admin-token-here', true, current_timestamp, current_timestamp, 'Admin API Token');

Step 3: Restart the OpenVSX Server

After modifying the database, you must restart your OpenVSX server instance. This ensures that the application loads the new user and its permissions from the database.

---

Deleting Extensions via the Admin API

Once you have your admin user and PAT, you can use a tool like curl to make requests to the Admin API.

The API endpoint for deleting extensions is:
POST /admin/api/extension/{namespaceName}/{extensionName}/delete

Scenario A: Deleting an Entire Extension

This will permanently remove an extension and all of its published versions.

curl -X POST \
  "http://<your-openvsx-server-url>/admin/api/extension/<namespaceName>/<extensionName>/delete?token=<your-admin-pat>"

Replace these placeholders:

• <your-openvsx-server-url>: The URL of your OpenVSX registry.
• <namespaceName>: The namespace of the extension.
• <extensionName>: The name of the extension.
• <your-admin-pat>: The PAT you created for the openvsx-admin user.

Scenario B: Deleting a Specific Version of an Extension

To remove only a specific version, you must send a JSON payload in the body of your request.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '[{"version": "1.2.3"}]' \
  "http://<your-openvsx-server-url>/admin/api/extension/<namespaceName>/<extensionName>/delete?token=<your-admin-pat>"

• The -d flag specifies the request body. You can list multiple versions to delete them in one request, for example: [{"version": "1.2.3"}, {"version": "1.2.4"}].

Scenario C: Deleting a Version for a Specific Target Platform

If an extension has platform-specific builds, you can delete a single variant by specifying the targetPlatform.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '[{"version": "1.3.0", "targetPlatform": "linux-x64"}]' \
  "http://<your-openvsx-server-url>/admin/api/extension/<namespaceName>/<extensionName>/delete?token=<your-admin-pat>"

---

Understanding Roles: admin vs. privileged

The OpenVSX codebase defines two special roles: admin and privileged. It is important to understand their difference:

• admin: This role is required to access the administrative API for tasks like deleting extensions, managing users, and modifying namespaces.
• privileged: This role is a "super-publisher." It allows a user to publish extensions to any namespace, bypassing the standard ownership rules. It does not grant access to the administrative API.

For the purpose of deleting extensions, you must use a user with the admin role.

---

Alternative Method: Direct Database Deletion (Advanced)

It is also possible to delete extensions by directly manipulating the database. This method is not recommended as it bypasses the application's business logic, which can lead to orphaned data or an inconsistent state. Only use this method if you cannot use the Admin API.

Critical Warning: Always back up your database before performing manual deletions. A mistake can cause permanent data loss.

To delete an extension, you must remove its associated records from multiple tables, including extension, extension_version, file_resource, and potentially others related to reviews and statistics. The relationships are complex, and the exact queries required are beyond the scope of this basic guide.

---

[netomi]

Since 0.30.0 any user can delete its own published extensions either via the UI or via endpoint, so there is no need to do it manually in the DB anymore.

[svor]

@netomi thank you for the response. Let me clarify my use case.

I’ve deployed OpenVSX 0.31.0 without any OAuth2 configuration. Since authentication is not configured, I cannot log in through the UI (which is fine for my setup, I need only the admin who can manage extensions).

I manually created a privileged user and a Personal Access Token directly in the database using INSERT INTO user_data and INSERT INTO personal_access_token. I then published extensions using ovsx with that PAT.

In this setup, it’s unclear how extensions can be deleted/unpublished. Is this possible through the UI? If not, it would be helpful to have documentation explaining how to delete extensions using the available API endpoints.

[netomi]

I see, thanks for the clarification. Setting up an oauth client from GitHub is not that hard though, but it might make sense to add the option to authenticate without an oauth provider, just as a local user to support such deployments as well (and would be beneficial for local testing / development as well).

[svor]

In most cases, the OpenShift clusters where we deploy the internal OpenVSX registry are restricted (air-gapped environments), and GitHub is not accessible. Therefore, configuring an OAuth client would not be a viable solution.

Given this context, does it make sense to keep this issue open and document how to delete extensions using the available API endpoints, or should we close it?

I can add this instructions specifically for OpenShift deployement into https://github.com/eclipse/openvsx/blob/master/deploy/openshift/README.md