> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/project-overview/migration-guide.md).

# Migration guidelines

Common migration paths from **OCS Inventory 2.x** to **OCS Inventory 3.x**.

This page focuses on **inventory continuity** and **migration best practices**. Check [System Requirements](/administrator-docs/system-requirements.md) for version and platform compatibility. See [Agent overview](/administrator-docs/agent-setup/agent-overview.md) and [Managing legacy devices](/administrator-docs/agent-setup/managing-legacy-devices.md) for the agent workflow.

### Before you begin

Make sure you can answer **yes** to these:

* Your target 3.x version includes the features you need from 2.x.
* Your legacy plugins (if any) are compatible with 3.x.
* You've read through the [Managing legacy devices](/administrator-docs/agent-setup/managing-legacy-devices.md) and [v2 vs v3: What’s changed?](/project-overview/v2-vs-v3-whats-changed.md) pages.
* You have a backup and rollback plan for the 2.x database and configuration.

{% hint style="warning" %}
Double check hardware resources before migrating. Running two agents or duplicating traffic will create additional load.
{% endhint %}

### Reference architectures

{% columns %}
{% column %}
{% @mermaid/diagram content="graph TD
subgraph Legacy\[OCS Inventory 2.x legacy]
direction TB
Agent\["Agent (2.x)"]
DNS\["DNS (inventory.company.tld)"]
ComServer\["Communication server"]
DB\[("Database")]
Console\["Web console (ocsreports)"]

```
Agent --> DNS --> ComServer --> DB
Console --> DB
```

end" %}
{% endcolumn %}

{% column %}
{% @mermaid/diagram content="graph TD
subgraph V3\[OCS Inventory 3.x]
direction TB
AgentNew\["Agent (3.x)"]
DNSNew\["DNS (inventory3.company.tld)"]
Backend\["Back end (REST API)"]
DBNew\[("Database")]
Front\["Web console"]

```
AgentNew --> DNSNew --> Backend --> DBNew
Front --> Backend
```

end

" %}
{% endcolumn %}
{% endcolumns %}

### Migration methods

<details>

<summary>Full replacement</summary>

Remove the 2.x stack and agents, then deploy the 3.x stack and 3.x agents.

**When to use**

* Very small fleet, low criticality, strong automation.

| Pros | Cons                                                                                                                                                         |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|      | <ul><li>Hard rollback if you already removed 2.x agents/infrastructure.</li><li>If anything breaks, you may temporarily lose inventory visibility.</li></ul> |

**Rollback / exit plan**

* Requires reinstalling 2.x components and restoring backups.

</details>

<details>

<summary>Parallel agents (run 2.x and 3.x agents side-by-side)</summary>

Run two agents on the same device:

* keep the **2.x agent** reporting to the legacy server
* install the **3.x agent** reporting to the new server

**When to use**

* You want validation with minimal risk
* You can afford to install a second agent on your assets.

| Pros                                                                                                           | Cons                                                       |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| <ul><li>Lowest risk for the legacy environment.</li><li>Easy side-by-side comparison of inventories.</li></ul> | <ul><li>Additional CPU/network usage on clients.</li></ul> |

For visual representation, see [#parallel-agents](#parallel-agents "mention").

</details>

<details>

<summary>Proxy duplication (duplicate 2.x traffic to 3.x)</summary>

Keep **2.x agents** unchanged. Put a reverse proxy in front of the legacy inventory endpoint. Duplicate incoming inventory traffic:

* one flow continues to 2.x
* one flow is forwarded to 3.x

**When to use**

* You have ongoing package deployments campaigns.
* Assets do not meet the minimal requirements for the 3.x agent.
* You need to keep 2.x operational while building up the 3.x environment.

| Pros                                                                                                           | Cons                                                         |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| <ul><li>No client-side change.</li><li>Progressive migration without interrupting legacy operations.</li></ul> | <ul><li>The proxy requires additional maintenance.</li></ul> |

For visual representation, see [#proxy-duplication](#proxy-duplication "mention").

</details>

<details>

<summary>Legacy endpoint (keep the 2.x URL, move the back end)</summary>

Decommission the 2.x servers, but keep:

* the legacy DNS hostname (example: `inventory.company.tld`)
* the 2.x agents still targeting that hostname

Run a reverse proxy that preserves the legacy path, redirecting traffic to 3.x.

| Pros                                                                                           | Cons                                                                                                         |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| <ul><li>2.x servers can be shut down.</li><li>Clients do not need immediate changes.</li></ul> | <ul><li>The proxy requires additional maintenance.</li><li>No side-by-side comparison with legacy.</li></ul> |

For visual representation, see [#legacy-endpoint](#legacy-endpoint "mention").

</details>

### Flow charts

#### Parallel agents

{% @mermaid/diagram content="graph TD
%% --- HOST (SAME ASSET) ---
subgraph Host\["Asset"]
direction TB
AgentOld\["Agent (2.X)"]
AgentNew\["Agent (3.X)"]
end

%% --- LEGACY BLOCK ---
subgraph Legacy\["Legacy 2.x"]
direction TB
DNSOld\["DNS (inventory.tld.domain)"]
ComServer\["Communication server"]
DBOld\[("Database")]
Console\["OCS Reports web console"]

```
   AgentOld --> DNSOld
   DNSOld --> ComServer
   ComServer --> DBOld
   Console --> DBOld
```

end

%% --- REWORK BLOCK ---
subgraph Rework\["3.x"]
direction TB
DNSNew\["DNS (newinventory.tld.domain)"]
Backend\["Backend server (REST API)"]
ORM\["ORM"]
DBNew\[("Database")]
Front\["Frontend"]

```
   AgentNew --> DNSNew
   DNSNew --> Backend
   Front --> Backend
   Backend --> ORM
   ORM --> DBNew
```

end" %}

#### Proxy duplication

{% @mermaid/diagram content="graph TD
%% --- LEGACY BLOCK ---
subgraph Legacy \[Legacy 2.x]
direction TB
AgentOld\["Agent (2.X)"]
DNSOld\["DNS (inventory.tld.domain)"]
RP\["Reverse proxy"]
ComServer\["Communication server"]
DBOld\[("Database")]
Console\["OCS Reports web console"]

```
    AgentOld --> DNSOld
    DNSOld --> RP
    RP --> ComServer
    ComServer --> DBOld
    Console --> DBOld
end

%% --- REWORK BLOCK ---
subgraph Rework [3.x]
    direction TB
    AgentNew["Agent (3.X)"]
    DNSNew["DNS (newinventory.tld.domain)"]
    Backend["Backend server (REST API)"]
    ORM["ORM"]
    DBNew[("Database")]
    Front["Frontend"]

    AgentNew --> DNSNew
    DNSNew --> Backend
    Front --> Backend
    Backend --> ORM
    ORM --> DBNew
end

%% --- MIGRATION LINKS ---
RP --->|Double flow| Backend

linkStyle 10 stroke-width:2px,fill:none,stroke:red,color:red;" %}
```

#### Legacy endpoint

{% @mermaid/diagram content="graph TD
%% --- LEGACY BLOCK ---
subgraph Legacy \[Legacy 2.x]
direction TB
AgentOld\["Agent (2.X)"]
DNSOld\["DNS (inventory.tld.domain)"]
RP\["Reverse proxy"]

```
    AgentOld --> DNSOld
    DNSOld --> RP
end

%% --- REWORK BLOCK ---
subgraph Rework [3.x]
    direction TB
    AgentNew["Agent (3.X)"]
    DNSNew["DNS (newinventory.tld.domain)"]
    Backend["Backend server (REST API)"]
    ORM["ORM"]
    DBNew[("Database")]
    Front["Frontend"]

    AgentNew --> DNSNew
    DNSNew --> Backend
    Front --> Backend
    Backend --> ORM
    ORM --> DBNew
end

%% --- MIGRATION LINKS ---
RP --->|Traffic redirection| Backend" %}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.ocsinventory-ng.org/project-overview/migration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.