Skip to content

Commit

Permalink
Merge pull request #1668 from reebhub/RDoc-2472_dockerMigrationPage
Browse files Browse the repository at this point in the history 
RDoc-2472_dockerMigrationPage
  • Loading branch information
@ppekrol
ppekrol committed Jun 28, 2023
2 parents 3801d83 + 79041cf commit 2314d1d
Show file tree
Hide file tree
Showing 3 changed files with 94 additions and 61 deletions.
6 changes: 6 additions & 0 deletions Documentation/6.0/Raven.Documentation.Pages/migration/server/.docs.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,11 @@
"Name": "Data migration",
"DiscussionId": "13abe0bb-5dda-45eb-9d3c-b0d64331d07d",
"Mappings": []
},
{
"Path": "docker.markdown",
"Name": "Docker",
"DiscussionId": "13abe0bb-5dda-45eb-9d3c-b0d64331d07d",
"Mappings": []
}
]
77 changes: 77 additions & 0 deletions Documentation/6.0/Raven.Documentation.Pages/migration/server/docker.markdown
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Migration: Migrating from Docker Image 5.x or lower to 6.0 or higher
---

{NOTE: }

* Starting from version `6.0` RavenDB for Docker introduces an
improved security model, using a dedicated user rather than `root`.
* RavenDB `6.0` and up also use a Debian archive file
([.deb package](../../start/installation/gnu-linux/deb)),
applying a uniform internal structure for Ubuntu OS platforms.
* To conform with these changes, installing RavenDB `6.0` or higher
in a system that already hosts RavenDB `5.x` or lower requires
the migration procedure explained below.
* Read [here](../../start/installation/running-in-docker-container) more about running a RavenDB Docker image.

* In this page:
* [Changes Made In RavenDB `6.0` And Up](../../migration/server/docker#changes-made-in-ravendb-6.0-and-up)
* [Migrating To `6.0` And Up](../../migration/server/docker#migrating-to-6.0-and-up)

{NOTE/}

---

{PANEL: Changes Made In RavenDB `6.0` And Up}

The **directory structure** used by RavenDB of version `6.0`
and above, and the **user** we use to run RavenDB, are different
from the directory structure and user used by older versions.

* RavenDB Docker images up to `5.x`:
* Create a unique directory structure under Windows.
* Are installed and accessed using the `root` user.

* RavenDB Docker images from `6.0` up:
* Use a Debian archive file ([.deb package](../../start/installation/gnu-linux/deb))
and create a similar directory structure under Windows and Ubuntu.
* Are installed and accessed using a dedicated `ravendb` user
instead of `root`, to improve security.

Learn below how to address these differences when migrating
from version `5.x` or lower to version `6.0` or higher.

{PANEL/}

{PANEL: Migrating To `6.0` And Up}

## Permit the `ravendb` user to access the image directory.

The default **UID** (User ID) and **GID** (Group ID)
used by `ravendb` are **999**.
Set the data directory permissions to these values (or
any other values you give `ravendb`).
E.g., `chown -R 999:999 $TARGET_DATA_DIR`

## Build the Ubuntu package

Build the Ubuntu package yourself with the same **UID** and
**GID** values, using the following arguments:
**UID**: `--build-arg "RAVEN_USER_ID=999"`
**GID**: `--build-arg "RAVEN_GROUP_ID=999"`
E.g., `docker build --build-arg "RAVEN_USER_ID=999" --build-arg "RAVEN_GROUP_ID=999" <...>`

## Migrate files and data

The setup process will create the directory structure detailed
[here](../../start/installation/gnu-linux/deb#file-system-locations).

The script within the image will attempt to link the old version's
data directory to the new version's data directory automatically.
If this attempt fails, an error will be produced.

When setup is done, **migrate or link** the contents stored in the
old RavenDB directories to the newly created directory structure.
Most notably, make sure that the **data** is available in its new
location: `/var/lib/ravendb/data`

{PANEL/}
72 changes: 11 additions & 61 deletions ...ven.Documentation.Pages/start/installation/running-in-docker-container.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,13 @@
{NOTE: }

* RavenDB can be launched using [Docker](https://www.docker.com/).
* **Stable** and **LTS** Docker images of RavenDB Server are available for
**Ubuntu** Linux and **Windows Nano Server**.
* Information related to setting and running RavenDB on Docker is available
in this page and in the RavenDB
* **Stable** and **LTS** Docker images of RavenDB Server are available
for **Ubuntu** Linux and **Windows Nano Server**.
* Information related to setting and running RavenDB on Docker is
available in this page and in the RavenDB
[dockerhub](https://hub.docker.com/r/ravendb/ravendb/) page.
* Starting from version `6.0` RavenDB introduces an improved security model,
using a dedicated user rather than `root`.
RavenDB `6.0` and up also use a Debian archive file
([.deb package](../../start/installation/gnu-linux/deb)), applying
a uniform internal structure for Ubuntu OS.
To conform with these changes, installing RavenDB 6.0 and higher
in a system that already hosts RavenDB `5.x` or older requires
a simple [migration](../../start/installation/running-in-docker-container#migration)
procedure.
* Upgrading RavenDB `5.x` or lower to RavenDB 6.0 or higher requires
a simple [migration](../../migration/server/docker) procedure.

* In this page:
* [Requirements](../../start/installation/running-in-docker-container#requirements)
Expand Down Expand Up @@ -171,54 +164,11 @@ By setting `RAVEN_License_Eula_Accepted=true` you're accepting our [terms & cond

{PANEL: Migration}

#### Changes made in RavenDB `6.0` and up:

The **user** that runs RavenDB `6.0` and up
and the **directory structure** used by these versions are
different from the user and structure used by older versions.

* RavenDB Docker images up to `5.x`:
* Create a unique directory structure under Windows.
* Are installed and accessed using the `root` user.

* RavenDB Docker images from `6.0` up:
* Use a Debian archive file ([.deb package](../../start/installation/gnu-linux/deb))
and create a similar directory structure under Windows and Ubuntu.
* Are installed and accessed using a dedicated `ravendb` user
instead of `root`, to improve security.

These differences need to be addressed when migrating from
version `5.x` or lower to version `6.0` and higher.

---

#### Migrating to `6.0` and up:

* Permit the `ravendb` user to access the image directory.
The default **UID** (User ID) and **GID** (Group ID)
used by `ravendb` are **999**.
Set the data directory permissions to these values (or
any other values you give `ravendb`).
`chown -R 999:999 $TARGET_DATA_DIR`

* Build the Ubuntu package yourself with the same **UID** and
**GID** values, using the following arguments:
**UID**: `--build-arg "RAVEN_USER_ID=999"`
**GID**: `--build-arg "RAVEN_GROUP_ID=999"`
E.g., `docker build --build-arg "RAVEN_USER_ID=999" --build-arg "RAVEN_GROUP_ID=999" <...>`

* Migrate files and data
The setup process will create the directory structure detailed
[here](../../start/installation/gnu-linux/deb#file-system-locations).

The script within the image will attempt to link the old version's
data directory to the new version's data directory automatically.
If this attempt fails, an error will be produced.

When setup is done, migrate or link the contents stored in the
old RavenDB directories to the newly created structure.
Most notably, make sure that the data is available in its new
location: `/var/lib/ravendb/data`
If a Docker image of RavenDB version `5.x` or lower is installed on your
system and you want to upgrade it to version `6.0` or higher, a short migration
process will be required.
Please visit our Docker [migration](../../migration/server/docker) page to
learn how to perform this migration.

{PANEL/}

Expand Down

0 comments on commit 2314d1d

Please sign in to comment.