diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/.docs.json b/Documentation/4.0/Raven.Documentation.Pages/start/installation/.docs.json index 7a56cb2920..cea3a167be 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/start/installation/.docs.json +++ b/Documentation/4.0/Raven.Documentation.Pages/start/installation/.docs.json @@ -37,7 +37,13 @@ "Path": "running-in-docker-container.markdown", "Name": "Running in a Docker Container", "DiscussionId": "ccf3a2ce-d124-4951-902c-2b9c63bb9f3f", - "Mappings": [] + "Mappings": [ + { + "Version": 6.0, + "Key": "start/containers/overview" + } + ], + "LastSupportedVersion": "5.4" }, { "Path": "upgrading-to-new-version.markdown", @@ -66,4 +72,4 @@ "DiscussionId": "05780903-e868-4ff3-84f6-044bf20b6103", "Mappings": [] } -] \ No newline at end of file +] diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json index 9465294541..b9d24b1be8 100644 --- a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json +++ b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json @@ -10,11 +10,5 @@ "Name": "AWS Linux VM", "DiscussionId": "4b49aee1-9637-42a0-b3b2-f65480a03cd6", "Mappings": [] - }, - { - "Path": "aws-docker-linux-vm.markdown", - "Name": "Docker on AWS EC2 Linux VM", - "DiscussionId": "176020b8-1083-4012-97a7-8905bfec8060", - "Mappings": [] } -] \ No newline at end of file +] diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/aws-docker-linux-vm.markdown b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/aws-docker-linux-vm.markdown deleted file mode 100644 index 9b8ab63441..0000000000 --- a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/aws-docker-linux-vm.markdown +++ /dev/null @@ -1,159 +0,0 @@ -# Setup Examples: Docker on AWS Linux VM - -In this walkthrough we will setup RavenDB using Docker on an AWS EC2 t2.micro virtual machine running Ubuntu 16.04. - -We will go through the necessary steps that are required for RavenDB to run securely including how to configure RavenDB -with the correct IP addresses and ports. - -It's recommended to read the [Setup Wizard](../../../start/installation/setup-wizard) section where you can find a detailed -explanation about the RavenDB setup process. - -## Create the VM - -Access the EC2 Dashboard, and click on Launch Instance. - -![1](images/aws-linux/1.png) - -Select your operating system. In our example we choose "Ubuntu Server 16.04 LTS (HVM), SSD Volume Type". - -![2](images/aws-linux/2.png) - -Select the machine type. We choose the t2.micro with 1 core and 1 GB of memory. - -![3](images/aws-linux/3.png) - -We stick with the basic default settings of the machine and configure just the minimal requirements for RavenDB. -You would probably want to go over the entire set of options and customize your VM. - -{WARNING:Security Concerns} -The following settings are fine if you just want to experiment with RavenDB, however when security is needed you should set -proper firewall rules and restrict access by IP. Please visit the [AWS security documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-security.html) -for more information about securing your VM. -{WARNING/} - -{NOTE:Elastic IP address} -By default, in AWS, an instance is assigned an IP addresses through DHCP. When the DHCP lease expires, or you restart the instance, this IP is released back to the pool and you will have to re-configure the RavenDB IP address. -To solve this problem, use an [Elastic IP address](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html) which doesn't change, and can even be dynamically re-assigned to other instances as you wish. -{NOTE/} - -Let's open ports 8080 and 38888 for use by RavenDB. You may choose other port numbers off course and restrict access by IP. -RavenDB will use port 8080 for HTTPS requests and port 38888 for TCP connections. We allow all incoming traffic on these ports by using 0.0.0.0. - -![ports](images/aws-docker/ports.png) - -Review your settings and launch the VM. - -![review](images/aws-docker/review.png) - -You will have to download a key pair which will be used later to connect to the machine using ssh. - -Wait a couple minutes for the machine to initialize and click connect. - -![connect](images/aws-docker/connect.png) - -Follow the instructions and connect to the new machine using ssh. - -{CODE-BLOCK:bash} -ssh -i "RavenDBUbuntuVMKeyPair.pem" ubuntu@ec2-54-200-27-219.us-west-2.compute.amazonaws.com -{CODE-BLOCK/} - -## Configure the VM - -Let's update the OS and install Docker. In Ubuntu it looks something like this: - -{CODE-BLOCK:bash} -curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - -sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" -sudo apt-get update -sudo apt-get install -y docker-ce -{CODE-BLOCK/} - -Run the following command to create a new RavenDB container. For more information visit the [Docker documentation section](../running-in-docker-container). - -{CODE-BLOCK:bash} -sudo docker run -d --name raven4 -p 8080:8080 -p 38888:38888 ravendb/ravendb -{CODE-BLOCK/} - -Use this command to view the status of your containers -{CODE-BLOCK:bash} -sudo docker ps -{CODE-BLOCK/} - -With the following command, you can view the full details of the container. Notice the IPAddress field (e.g. 172.17.0.2). This is the **private IP address** that RavenDB binds to inside the container. You will use this address later in the wizard. -{CODE-BLOCK:bash} -sudo docker inspect raven4 -{CODE-BLOCK/} - -You can connect to the container using -{CODE-BLOCK:bash} -sudo docker exec -it raven4 bash -{CODE-BLOCK/} - -And then you can connect to the RavenDB CLI using: -{CODE-BLOCK:bash} -./rvn admin-channel -{CODE-BLOCK/} - -## Run the RavenDB Setup Wizard - -You have a few choices on how to run the RavenDB server. -We will use the [Setup Wizard](../../../start/installation/setup-wizard), but you can also configure things [manually](../../../start/installation/manual). - -RavenDB is running and you can access it from your (local) browser using the VM's Public DNS (e.g. http://ec2-54-200-27-219.us-west-2.compute.amazonaws.com:8080). - -![browser](images/aws-docker/browser.png) - -Accept the agreement and choose the setup type you want to do. In the example we choose to setup securely with a Let's Encrypt certificate. -You will need to claim your domain, read more [here](../../../start/installation/setup-wizard#secure-setup-with-a-let). - -When you reach the point where you have to enter the IP addresses, you can go to the EC2 management console and check the machine's public IP address. - -![addresses](images/aws-docker/addresses.png) - -Back in the wizard, enter the private IP address RavenDB binds to (e.g. 172.17.0.2) in the "IP Address / Hostname" field. - -Check the External IP box and enter the **public IP address** of the VM (e.g. 54.200.27.219). Make sure to enter the ports you exposed in the docker run command in the "External Port" fields (8080 and 38888 in our example). - -Start the installation. - -![ips](images/aws-docker/ips.png) - -If you encounter errors during the process, please visit the [FAQ section](../../../server/security/common-errors-and-faq). - -When the setup is finished, you will receive a configuration ZIP file which contains an admin client certificate which will allow you to connect using the browser. Keep the file safe. - -Restart the server. - -![restart](images/aws-docker/restart.png) - -## Access the Studio - -If everything went well, you should be redirected to the studio and Chrome should let you choose the client certificate to use (the one which was just created). - -Some environments don't allow to set the client certificate automatically in the setup wizard so if you are not redirected to the Studio, and you get an authentication error, please **close all instances of the browser** and install the admin client certificate manually. - -Now you can access the Studio, open the browser and enter your new domain (e.g. https://a.docker.development.run). - -Chrome will let you select the certificate. - -![cert](images/aws-docker/cert.png) -![studio](images/aws-docker/studio.png) - -Access the certificate view to see both the loaded server certificate and the admin client certificate. Make sure to read the [security section](../../../server/security/overview) for better understanding of certificates and security issues. - -![certview](images/aws-docker/certview.png) - -Congratulations, you have a secure RavenDB server running on Docker on a simple EC2 machine. Have fun with it! - -Connecting a few servers in a cluster is easy. Follow [these instructions](../../../start/installation/setup-wizard) to construct a cluster during setup. - -## Related Articles - -### Getting Started - -- [Getting Started](../../../start/getting-started) - -### Installation - -- [Setup Wizard](../../../start/installation/setup-wizard) -- [Manual Setup](../../../start/installation/manual) diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/addresses.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/addresses.png deleted file mode 100644 index a97268e649..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/addresses.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/addresses.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/addresses.snag deleted file mode 100644 index ef2c0e01f0..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/addresses.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/browser.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/browser.png deleted file mode 100644 index 1010135695..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/browser.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/browser.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/browser.snag deleted file mode 100644 index 5f777b4f54..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/browser.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/cert.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/cert.png deleted file mode 100644 index 41f08ed8a1..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/cert.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/cert.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/cert.snag deleted file mode 100644 index 3b0dd6d971..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/cert.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/certview.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/certview.png deleted file mode 100644 index 139068df86..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/certview.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/certview.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/certview.snag deleted file mode 100644 index b4ed963631..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/certview.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/connect.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/connect.png deleted file mode 100644 index 7d58085a34..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/connect.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/connect.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/connect.snag deleted file mode 100644 index 37c04b3a9c..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/connect.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ips.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ips.png deleted file mode 100644 index 9682dc22c9..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ips.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ips.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ips.snag deleted file mode 100644 index 90e8f3951b..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ips.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ports.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ports.png deleted file mode 100644 index c2a4bd8544..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ports.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ports.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ports.snag deleted file mode 100644 index 6e59b1c922..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/ports.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/restart.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/restart.png deleted file mode 100644 index 20288664a7..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/restart.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/restart.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/restart.snag deleted file mode 100644 index 685d0191a1..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/restart.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/review.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/review.png deleted file mode 100644 index 93022c985f..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/review.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/review.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/review.snag deleted file mode 100644 index 47d71b6f29..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/review.snag and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/studio.png b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/studio.png deleted file mode 100644 index dca2fd9670..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/studio.png and /dev/null differ diff --git a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/studio.snag b/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/studio.snag deleted file mode 100644 index d9d882071a..0000000000 Binary files a/Documentation/4.0/Raven.Documentation.Pages/start/installation/setup-examples/images/aws-docker/studio.snag and /dev/null differ diff --git a/Documentation/4.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown b/Documentation/4.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown index 930cf5bc8c..0b46374fde 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown @@ -396,7 +396,6 @@ To figure out what the new limit should be, look at the exception thrown by Rave - [AWS Windows VM](../../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) ### Security diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/getting-started.markdown b/Documentation/4.1/Raven.Documentation.Pages/start/getting-started.markdown index 0c2278c517..194d5e177a 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/getting-started.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/start/getting-started.markdown @@ -61,7 +61,6 @@ If you are interested in hosting the server on a VM, please refer to - [AWS Windows VM](../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../start/installation/setup-examples/aws-docker-linux-vm) {NOTE/} diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/.docs.json b/Documentation/4.1/Raven.Documentation.Pages/start/installation/.docs.json index 245d43aca9..5b730dd490 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/.docs.json +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/.docs.json @@ -37,7 +37,13 @@ "Path": "running-in-docker-container.markdown", "Name": "Running in a Docker Container", "DiscussionId": "eda38daa-a361-4114-9519-0684a7e1bda2", - "Mappings": [] + "Mappings": [ + { + "Version": 6.0, + "Key": "start/containers/overview" + } + ], + "LastSupportedVersion": "5.4" }, { "Path": "upgrading-to-new-version.markdown", @@ -66,4 +72,4 @@ "DiscussionId": "05780903-e868-4ff3-84f6-044bf20b6103", "Mappings": [] } -] \ No newline at end of file +] diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown b/Documentation/4.1/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown index 9026738ce7..aba594e5cd 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown @@ -185,5 +185,4 @@ For more detailed information on how to use and setup RavenDB on Docker, please ### Setup Examples -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json index 5f5aaa8963..d94eaaf9af 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/.docs.json @@ -15,11 +15,5 @@ "Name": "AWS Linux VM", "DiscussionId": "4b49aee1-9637-42a0-b3b2-f65480a03cd6", "Mappings": [] - }, - { - "Path": "aws-docker-linux-vm.markdown", - "Name": "Docker on AWS EC2 Linux VM", - "DiscussionId": "176020b8-1083-4012-97a7-8905bfec8060", - "Mappings": [] } -] \ No newline at end of file +] diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/aws-eks.markdown b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/aws-eks.markdown index aaaf5f1581..4c1c7bf935 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/aws-eks.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/aws-eks.markdown @@ -169,6 +169,5 @@ kubectl delete sts ravendb ### Installation - [Setup Wizard](../../../../start/installation/setup-wizard) -- [Setup Examples: Docker (AWS ECS)](../../../../start/installation/setup-examples/aws-docker-linux-vm) - [Setup Examples: Windows VM (AWS)](../../../../start/installation/setup-examples/aws-windows-vm) - [Setup Examples: Linux VM (AWS)](../../../../start/installation/setup-examples/aws-linux-vm) diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/azure-aks.markdown b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/azure-aks.markdown index 58fec14ee3..46c47104c3 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/azure-aks.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/azure-aks.markdown @@ -161,6 +161,5 @@ kubectl delete sts ravendb ### Installation - [Setup Wizard](../../../../start/installation/setup-wizard) -- [Setup Examples: Docker (AWS ECS)](../../../../start/installation/setup-examples/aws-docker-linux-vm) - [Setup Examples: Windows VM (AWS)](../../../../start/installation/setup-examples/aws-windows-vm) - [Setup Examples: Linux VM (AWS)](../../../../start/installation/setup-examples/aws-linux-vm) diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/google-gke.markdown b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/google-gke.markdown index c02ed6cba8..30c6d71429 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/google-gke.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-examples/Kubernetes/google-gke.markdown @@ -167,6 +167,5 @@ kubectl delete sts ravendb ### Installation - [Setup Wizard](../../../../start/installation/setup-wizard) -- [Setup Examples: Docker (AWS ECS)](../../../../start/installation/setup-examples/aws-docker-linux-vm) - [Setup Examples: Windows VM (AWS)](../../../../start/installation/setup-examples/aws-windows-vm) - [Setup Examples: Linux VM (AWS)](../../../../start/installation/setup-examples/aws-linux-vm) diff --git a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown index 01920f90c1..705493c04d 100644 --- a/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown +++ b/Documentation/4.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown @@ -368,4 +368,3 @@ Learn more in [Adding a Node to a Cluster](../../studio/server/cluster/add-node- - [Manual Setup](../../start/installation/manual) - [Setup Example - AWS Windows VM](../../start/installation/setup-examples/aws-windows-vm) - [Setup Example - AWS Linux VM](../../start/installation/setup-examples/aws-linux-vm) -- [Setup Example - Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) diff --git a/Documentation/4.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown b/Documentation/4.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown index 4a66f86b95..5b944d9290 100644 --- a/Documentation/4.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown +++ b/Documentation/4.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown @@ -421,7 +421,6 @@ To figure out what the new limit should be, look at the exception thrown by Rave - [AWS Windows VM](../../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) ### Security diff --git a/Documentation/4.2/Raven.Documentation.Pages/start/getting-started.markdown b/Documentation/4.2/Raven.Documentation.Pages/start/getting-started.markdown index b0a22ddf54..14a9b5d029 100644 --- a/Documentation/4.2/Raven.Documentation.Pages/start/getting-started.markdown +++ b/Documentation/4.2/Raven.Documentation.Pages/start/getting-started.markdown @@ -61,7 +61,6 @@ If you are interested in hosting the server on a VM, please refer to - [AWS Windows VM](../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../start/installation/setup-examples/aws-docker-linux-vm) {NOTE/} diff --git a/Documentation/5.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown b/Documentation/5.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown index d2676466ee..610bd5fbf8 100644 --- a/Documentation/5.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown +++ b/Documentation/5.1/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown @@ -558,7 +558,6 @@ To figure out what the new limit should be, look at the exception thrown by Rave - [AWS Windows VM](../../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) ### Security diff --git a/Documentation/5.1/Raven.Documentation.Pages/start/getting-started.markdown b/Documentation/5.1/Raven.Documentation.Pages/start/getting-started.markdown index 4b6db02cea..676fbaed31 100644 --- a/Documentation/5.1/Raven.Documentation.Pages/start/getting-started.markdown +++ b/Documentation/5.1/Raven.Documentation.Pages/start/getting-started.markdown @@ -104,7 +104,6 @@ If you are interested in hosting the server on a VM, please refer to - [AWS Windows VM](../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../start/installation/setup-examples/aws-docker-linux-vm) {NOTE/} diff --git a/Documentation/5.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown b/Documentation/5.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown index 4eeb68c06e..f99ed9cf48 100644 --- a/Documentation/5.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown +++ b/Documentation/5.1/Raven.Documentation.Pages/start/installation/setup-wizard.markdown @@ -669,4 +669,3 @@ Learn more in [Adding a Node to a Cluster](../../studio/cluster/setting-a-cluste - [Running in a Docker Container](../../start/installation/running-in-docker-container) - [Setup Example - AWS Windows VM](../../start/installation/setup-examples/aws-windows-vm) - [Setup Example - AWS Linux VM](../../start/installation/setup-examples/aws-linux-vm) -- [Setup Example - Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) diff --git a/Documentation/5.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown b/Documentation/5.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown index 1994da2032..03d229ab89 100644 --- a/Documentation/5.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown +++ b/Documentation/5.2/Raven.Documentation.Pages/server/security/common-errors-and-faq.markdown @@ -533,7 +533,6 @@ To figure out what the new limit should be, look at the exception thrown by Rave - [AWS Windows VM](../../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) ### Security diff --git a/Documentation/5.2/Raven.Documentation.Pages/start/getting-started.markdown b/Documentation/5.2/Raven.Documentation.Pages/start/getting-started.markdown index 05fdcc6ed1..8e3abd05ff 100644 --- a/Documentation/5.2/Raven.Documentation.Pages/start/getting-started.markdown +++ b/Documentation/5.2/Raven.Documentation.Pages/start/getting-started.markdown @@ -104,7 +104,6 @@ If you are interested in hosting the server on a VM, please refer to - [AWS Windows VM](../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../start/installation/setup-examples/aws-docker-linux-vm) {NOTE/} diff --git a/Documentation/5.3/Raven.Documentation.Pages/start/installation/gnu-linux/deb.markdown b/Documentation/5.3/Raven.Documentation.Pages/start/installation/gnu-linux/deb.markdown index 735838d9a9..81f03ae118 100644 --- a/Documentation/5.3/Raven.Documentation.Pages/start/installation/gnu-linux/deb.markdown +++ b/Documentation/5.3/Raven.Documentation.Pages/start/installation/gnu-linux/deb.markdown @@ -294,4 +294,3 @@ WantedBy=multi-user.target - [Running as a Service](../../../start/installation/running-as-service) - [Setup Example - AWS Windows VM](../../../start/installation/setup-examples/aws-windows-vm) - [Setup Example - AWS Linux VM](../../../start/installation/setup-examples/aws-linux-vm) -- [Setup Example - Docker on AWS Linux VM](../../../start/installation/setup-examples/aws-docker-linux-vm) diff --git a/Documentation/6.0/Raven.Documentation.Pages/migration/client-api/client-breaking-changes.markdown b/Documentation/6.0/Raven.Documentation.Pages/migration/client-api/client-breaking-changes.markdown index 48181a1dbe..1484deeafe 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/migration/client-api/client-breaking-changes.markdown +++ b/Documentation/6.0/Raven.Documentation.Pages/migration/client-api/client-breaking-changes.markdown @@ -150,7 +150,7 @@ var backupResult = (ShardedBackupResult)result; ### Installation - [Setup Wizard](../../start/installation/setup-wizard) - [System Requirements](../../start/installation/system-requirements) -- [Running in a Docker Container](../../start/installation/running-in-docker-container) +- [Running in a Container](../../start/containers/overview) ### Session - [Introduction](../../client-api/session/what-is-a-session-and-how-does-it-work) diff --git a/Documentation/6.0/Raven.Documentation.Pages/migration/server/docker.markdown b/Documentation/6.0/Raven.Documentation.Pages/migration/server/docker.markdown index 21f068f21b..1a81336270 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/migration/server/docker.markdown +++ b/Documentation/6.0/Raven.Documentation.Pages/migration/server/docker.markdown @@ -11,7 +11,7 @@ * 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. +* Read [here](../../start/containers/image-usage) 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) diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/.docs.json b/Documentation/6.0/Raven.Documentation.Pages/start/.docs.json index 7d6a94f133..41fcaf791b 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/start/.docs.json +++ b/Documentation/6.0/Raven.Documentation.Pages/start/.docs.json @@ -53,5 +53,10 @@ "Path": "/licensing", "Name": "Licensing", "Mappings": [] + }, + { + "Path": "/containers", + "Name": "Containers", + "Mappings": [] } ] diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/.docs.json b/Documentation/6.0/Raven.Documentation.Pages/start/containers/.docs.json new file mode 100644 index 0000000000..8d655f573f --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/.docs.json @@ -0,0 +1,50 @@ +[ + + { + "Path": "overview.markdown", + "Name": "General Guide", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [ + { + "Version": 5.2, + "Key": "start/installation/running-in-docker-container" + }, + { + "Version": 5.1, + "Key": "start/installation/running-in-docker-container" + }, + { + "Version": 5.0, + "Key": "start/installation/running-in-docker-container" + }, + { + "Version": 4.2, + "Key": "start/installation/running-in-docker-container" + }, + { + "Version": 4.1, + "Key": "start/installation/running-in-docker-container" + }, + { + "Version": 4.0, + "Key": "start/installation/running-in-docker-container" + } + ] + }, + { + "Path": "image-usage.markdown", + "Name": "Docker Images", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + { + "Path": "/dockerfile", + "Name": "Dockerfile", + "Mappings": [] + }, + { + "Path": "/requirements", + "Name": "Requirements", + "Mappings": [] + } +] diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/.docs.json b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/.docs.json new file mode 100644 index 0000000000..195a7212a4 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/.docs.json @@ -0,0 +1,21 @@ +[ + + { + "Path": "guide.markdown", + "Name": "Start", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + { + "Path": "dockerfile-overview.markdown", + "Name": "Overview", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + { + "Path": "extending.markdown", + "Name": "Extending & Tuning", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + } +] diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/dockerfile-overview.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/dockerfile-overview.markdown new file mode 100644 index 0000000000..4e397ae2d1 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/dockerfile-overview.markdown @@ -0,0 +1,149 @@ +# Dockerfile overview + +Let's familiarize ourselves with [RavenDB Dockerfile](https://github.com/ravendb/ravendb/blob/v6.2/docker/ravendb-ubuntu/Dockerfile.x64). + + +##### Setting the Base Image +{CODE-BLOCK:bash} +FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-jammy +{CODE-BLOCK/} + +The `FROM` instruction sets the base image for the Dockerfile. +In this case, it uses Microsoft's lightweight .NET runtime dependencies image, specifically tailored for Ubuntu. +This provides a minimal foundation for running RavenDB in Docker, keeping the image size smaller and focusing only on required dependencies. + + +##### Defining Build Arguments +{CODE-BLOCK:bash} +ARG PATH_TO_DEB RAVEN_USER_ID RAVEN_GROUP_ID +{CODE-BLOCK/} + +Here, three build arguments (`ARG`) are defined: + +- `PATH_TO_DEB`: Specifies the path to the `.deb` package for installing RavenDB. +- `RAVEN_USER_ID` and `RAVEN_GROUP_ID`: Used to configure the user and group IDs for the `ravendb` user, ensuring proper file permissions and container security. + +These arguments are placeholders to be replaced at build time with actual values. + + +##### Installing Required Dependencies +{CODE-BLOCK:bash} +RUN apt-get update \ + && apt-get install \ + && apt-get install --no-install-recommends openssl jq curl -y +{CODE-BLOCK/} + + +The `RUN` instruction executes commands to prepare the container environment: + +- `apt-get update`: Updates the package list. +- `apt-get update`: Updates the OS package list. +- `apt-get install`: Installs system tools responsible for: + - `openssl`: managing TLS certificates + - `jq`: swiss army knife for handling JSON data + - `curl`: performing HTTP(S) requests + +The `--no-install-recommends` flag minimizes the installation of optional dependencies, keeping the image lean. + + +##### Setting Environment Variables + +This section declares default values for environment variables configuring the image runtime. The settings file in RavenDB Docker image is empty and most of the configuration would usually be passed through environment variables. + +{CODE-BLOCK:bash} +ENV RAVEN_ARGS='' \ + RAVEN_SETTINGS='' \ + RAVEN_IN_DOCKER='true' \ + RAVEN_Setup_Mode='Initial' \ + .... +{CODE-BLOCK/} + + +###### Key Environment Variables (Brief Overview) + +- **`RAVEN_IN_DOCKER`**: Flag that RavenDB is running in a Dockerized environment for optimal behavior adjustments. +- **`RAVEN_Setup_Mode`**: `'Initial'` enables the setup wizard on the first run. +- **`RAVEN_DataDir`**: Defines where database files are stored (default `/var/lib/ravendb/data`), typically mounted as a volume for persistence. +- **`RAVEN_Security_MasterKey_Path`**: Path to the encryption master key for securing sensitive data. +- **`RAVEN_Security_UnsecuredAccessAllowed`**: `'PrivateNetwork'` permits unsecured access only within private networks, enhancing security if you run unsecured. +- **`RAVEN_ServerUrl_Tcp`**: Specifies the TCP port (`38888`) used for cluster communication between nodes. + +These variables enable flexible configuration for development, testing, or production environments. + +##### Exposing Ports +{CODE-BLOCK:bash} +EXPOSE 8080 38888 161 +{CODE-BLOCK/} + +The `EXPOSE` instruction declares the ports that RavenDB uses: + +- `8080`: The primary HTTP port for web-based interactions. +- `38888`: TCP port for cluster communication. +- `161`: SNMP (Simple Network Management Protocol) port. + +This doesn’t bind the ports but informs users about which ones are available. + +##### Adding the RavenDB Package +{CODE-BLOCK:bash} +COPY "${PATH_TO_DEB}" /opt/ravendb.deb + +RUN apt install /opt/ravendb.deb -y \ + && apt-get autoremove -y \ + && rm -rf /var/lib/apt/lists/* +{CODE-BLOCK/} + +This section installs RavenDB: + +1. The `COPY` command transfers the `.deb` package (RavenDB’s installation file) into the container at `/opt/ravendb.deb`. +2. The `RUN` command installs the package using `apt`, cleans up unnecessary files to reduce the image size - removes cached OS package lists (`/var/lib/apt/lists/*`). + +--- + +##### Adding Scripts and Configuration +{CODE-BLOCK:bash} +COPY server-utils.sh cert-utils.sh run-raven.sh healthcheck.sh link-legacy-datadir.sh /usr/lib/ravendb/scripts/ +COPY --chown=root:${RAVEN_USER_ID} --chmod=660 settings.json /etc/ravendb +{CODE-BLOCK/} + +- Several utility scripts (`server-utils.sh`, `cert-utils.sh`, etc.) are copied into the container. These scripts manage server initialization, health checks, and certificates. +- `settings.json`, a configuration file, is copied into `/etc/ravendb` with specific ownership (`root:${RAVEN_USER_ID}`) and permissions (`660`) for security. + +--- + +##### Setting the User and Health Check +{CODE-BLOCK:bash} +USER ravendb:ravendb + +HEALTHCHECK --start-period=60s CMD /usr/lib/ravendb/scripts/healthcheck.sh +{CODE-BLOCK/} + +1. `USER`: Switches the container to run as the `ravendb` user instead of `root`, improving security. +2. `HEALTHCHECK`: Defines a command to verify RavenDB's health. The script (`healthcheck.sh`) is run after a 60-second delay to allow the server to initialize. + +--- + +##### Declaring Volumes +{CODE-BLOCK:bash} +VOLUME /var/lib/ravendb/data /etc/ravendb +{CODE-BLOCK/} + +`VOLUME` specifies directories to be mounted as volumes. These are: + +- `/var/lib/ravendb/data`: For database files. +- `/etc/ravendb`: For configuration and security-related files. + +Ensures that data persists outside the container lifecycle, using volumes. + +--- + +##### Setting the Working Directory and Entry Command +{CODE-BLOCK:bash} +WORKDIR /usr/lib/ravendb + +CMD [ "/bin/bash", "/usr/lib/ravendb/scripts/run-raven.sh" ] +{CODE-BLOCK/} + +- `WORKDIR`: Sets the default working directory inside the container, simplifying subsequent commands. +- `CMD`: Specifies the command to run when the container starts. Here, it launches a Bash shell to execute the `run-raven.sh` script, which handles server initialization and starts RavenDB. + +--- diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/extending.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/extending.markdown new file mode 100644 index 0000000000..848f585a4c --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/extending.markdown @@ -0,0 +1,169 @@ +# Extending & Modifying RavenDB Dockerfile + +Some custom setups solutions may lead you to a necessity of building over our Dockerfile, or even customizing it. +This article explains in detail, how it works. + + +For detailed Dockerfile guide, visit [Containers > Dockerfile > Overview](./dockerfile-overview) + +## Extending the Existing `ravendb/ravendb` Image + + +This approach involves using `FROM ravendb/ravendb` to build upon the official image, adding custom commands, scripts, or configurations. + + +##### Why Should I Extend the RavenDB Dockerfile? + +- **Simple customization:** Ideal for small, incremental changes that do not require rebuilding the entire image from scratch. +- **Keeps RavenDB's default behavior:** Build on top of the existing official `ravendb/ravendb` image while preserving core functionality. +- **Customization of startup scripts:** Provides flexibility to replace the `run-raven.sh` startup script with a custom, more focused version tailored to your deployment needs. + +##### **Dockerfile Example for Extension** + +{CODE-BLOCK:bash} +# Use the official RavenDB image as the base +FROM ravendb/ravendb:7.0-ubuntu-latest + +# Add your custom script or commands +COPY my-script.sh /usr/lib/ravendb/scripts/my-script.sh +RUN chmod +x /usr/lib/ravendb/scripts/my-script.sh + +# Add an environment variable +ENV MY_CUSTOM_VAR="MyValue" + +# Customize the HEALTHCHECK +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ + CMD curl -f http://localhost:8080 || exit 1 + +# Replace the CMD (optional!) +COPY my-run-raven.sh /usr/lib/ravendb/scripts/run-raven.sh +CMD ["/bin/bash", "/usr/lib/ravendb/scripts/run-raven.sh"] +{CODE-BLOCK/} + +##### Building for Multiple Platforms + +Use BuildX if you need to build for multiple architectures (e.g., x64, arm64): + +{CODE-BLOCK:bash} +docker buildx build --platform linux/amd64,linux/arm64 -t my-ravendb . +{CODE-BLOCK/} + +##### Tips +You can: + +- Add scripts that configure or extend RavenDB's behavior (e.g., preloading data or setting specific configurations). Ensure scripts are executable (chmod +x). +- Pass custom values or configurations via ENV directives or at runtime using docker run -e. +- Customize HEALTHCHECK to match your deployment’s requirements, ensuring RavenDB is responding as expected. + + +--- + +## Customizing the RavenDB Dockerfile + +If your use case requires more extensive customization, you can modify the Dockerfile directly to create a tailored image. + +##### Possibilities of modifications + +###### Change the Base Image +Replace `FROM mcr.microsoft.com/dotnet/runtime-deps:8.0-jammy` with another OS, such as `debian:buster` or `alpine:latest`. + +However, make sure to select one that includes .NET runtime dependencies or install them on your own. + +###### Add Custom Dependencies +Use `RUN` commands to install additional dependencies specific to your environment. + +###### Customize Environment Variables +Adjust `ENV` declarations to preconfigure RavenDB settings, such as data directories or logs. +You can do the same thing in Docker using `-e` argument without tinkering with the Dockerfiles, but may want to have this fixed in the image. + +###### Replace the Entry Script +Copy and use a custom `run-raven.sh` script: +{CODE-BLOCK:bash} +COPY my-run-raven.sh /usr/lib/ravendb/scripts/run-raven.sh +CMD ["/bin/bash", "/usr/lib/ravendb/scripts/run-raven.sh"] +{CODE-BLOCK/} + + +## Entry Script ([run-raven.sh)](https://github.com/ravendb/ravendb/blob/v6.2/docker/ravendb-ubuntu/run-raven.sh) + +This script initializes and runs the RavenDB server. +It's designed to work for anyone, so in some scenarios you may want to chisel it down a bit, modify, or completely replace, which we'll cover next. +Key responsibilities include: + +###### Legacy Data Migration +{CODE-BLOCK:bash} +/usr/lib/ravendb/scripts/link-legacy-datadir.sh +{CODE-BLOCK/} + +This script was created to handle legacy data volumes, that were working with RavenDB before 6.0. +The data had different directory structure inside Linux back then, so we needed to migrate them properly after update to 6.0+. + +###### Command Construction +Constructs the RavenDB server start command using arguments and environment variables: +{CODE-BLOCK:bash} +COMMAND="/usr/lib/ravendb/server/Raven.Server" +{CODE-BLOCK/} + +###### Certificate Checks +Ensures proper certificate configuration for secure HTTPS connections. + +###### Startup Environment Setup + +Configures the `RAVEN_ServerUrl` environment variable if not already set. + +###### Graceful Shutdown + +Handles termination signals to cleanly stop the server. + +###### Database Auto-Creation +Calls a utility script to create the database if the `RAVEN_DATABASE` environment variable is set. + +## Replacing run-raven.sh + +Replacing allows full control of the startup process for both extending and modifying approaches. The only requirement is that **the script must ultimately run the RavenDB server**. Everything else is optional and can be customized to fit your specific needs. Some ideas include: + +###### Certificates management + +Retrieve and configure SSL certificates, such as from a secure vault or web server. + +###### Exports Environment Variables + +Define and set variables like `RAVEN_ServerUrl` to match your deployment requirements. + +###### Handles Shutdown Gracefully + +Use signal trapping for smooth termination of the server: +{CODE-BLOCK:bash} +trap 'kill -TERM "$COMMANDPID"' TERM INT +{CODE-BLOCK/} + +###### Custom Operations +Add database initialization or additional setup scripts as needed. + +--- + +##### **Example Custom Script** + +{CODE-BLOCK:bash} +# Custom startup script for RavenDB + +echo "Starting custom RavenDB setup..." + +# Get and configure certificates +get_certificates() { + # Implement logic to retrieve certificates, e.g., from a web server or secured vault +} + +check_for_certificates + +# Start RavenDB +COMMAND="/usr/lib/ravendb/server/Raven.Server -c /etc/ravendb/settings.json" +$COMMAND & +COMMANDPID=$! + +# Handle shutdown gracefully +trap 'kill -TERM "$COMMANDPID"' TERM INT +wait $COMMANDPID +{CODE-BLOCK/} + +--- diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/guide.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/guide.markdown new file mode 100644 index 0000000000..c36b443877 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/dockerfile/guide.markdown @@ -0,0 +1,17 @@ +# Working with RavenDB's Dockerfile + +RavenDB’s image and Dockerfile provide a universal and flexible base. +If you need to, you can either extend the existing `ravendb/ravendb` image with your modifications or build a new image entirely by tweaking its Dockerfile. +Additionally, for complex scenarios, you can replace the default entry script (`run-raven.sh`) in both cases to fully customize the startup process. + + +- To learn about Dockerfile, visit this page: [Containers > Dockerfile > Overview](./dockerfile-overview) + + +- If you want to modify the image, or use it as a base, go here: [Containers > Dockerfile > Extending & Tuning](./extending) + + +- To go deep with running RavenDB on prod in containers, visit our requirements knowledge base: [Containers > Requirements](../requirements), or read some of our [articles](https://ravendb.net/articles) - look for deployment guides. + + +- If you have encountered a unique significant problem, contact our [support](https://ravendb.net/support) for help. diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/image-usage.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/image-usage.markdown new file mode 100644 index 0000000000..73bba507d2 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/image-usage.markdown @@ -0,0 +1,150 @@ +# RavenDB Images + +## Usage +RavenDB offers official images based on Ubuntu and Windows NanoServer. + +--- + +First, let's describe basic development usage of our images. +We'll **focus on basics**, not going *too deep* into security, networking and storage. +For detailed instructions on how to spin up your production, you can read our guides for specific container/orchestration platforms - **deployment articles**, or go *deep* with **https://ravendb.net/docs/start/containers** knowledge-base. + +To quickly try out RavenDB, you can run the following command: + +{CODE-BLOCK:bash} +docker run -it --rm -p 8080:8080 ravendb/ravendb +{CODE-BLOCK/} + +This will: + +1. Download the appropriate image from DockerHub (if not already cached). +2. Run RavenDB, exposing the web interface on port `8080`. +3. Enter the container shell. +4. Kill and remove the container at exit. + + +#### **Available Tags** + +RavenDB images are available in the following flavors: + +- `latest`/`latest-lts`: The latest stable or latest long-term support (LTS) version of RavenDB +- `ubuntu-latest / ubuntu-latest-lts`: Ubuntu floating tags +- `windows-latest`, `windows-latest-lts`: Windows Nanoserver floating tags +- **Fixed** tags like `6.2.2-ubuntu.22.04-arm32v7`, `6.0.108-ubuntu.22.04-x64`, `6.2.2-windows-1809`, and more. Check the full [tags list](https://hub.docker.com/r/ravendb/ravendb/tags) for details. + +#### **Runtime customization** + +While running your container with RavenDB inside, you may need to use some options, that either modify the container behavior, or edit Raven configuration. +Here are some examples: + +| **Option** | **Description** | +|-------------------------------------------------------------------|-------------------------------------------------------------------------| +| `-p 8080:8080` | Maps the RavenDB web interface to port `8080` on the host machine. | +| `-v /my/config:/etc/ravendb` | Mounts a custom configuration directory. | +| `-v /my/data:/var/lib/ravendb/data` | Mounts a custom data directory for persistence. | +| `-e RAVEN_Setup_Mode=Initial` | Configures the setup mode (e.g., `None`, `Initial`, `LetsEncrypt`). | +| `-e RAVEN_ServerUrl=http://0.0.0.0:46290` | Run RavenDB on custom HTTP port. | +| `-e RAVEN_Logs_Mode=Operations` (in 7.0+: `RAVEN_Logs_Min_Level`) | Sets the logging level. | +| `-e RAVEN_Security_UnsecuredAccessAllowed=PublicNetwork` | Allows unsecured access for development purposes. | +| `--restart unless-stopped` | Ensures the container restarts automatically unless explicitly stopped. | + +#### **Using Environment Variables to Configure RavenDB** + +RavenDB's behavior can be configured through environment variables. These variables allow you to: + +- Disable the setup wizard: `RAVEN_Setup_Mode=None` +- Set RavenDB License: `RAVEN_License` +- Set Public Server Url: `RAVEN_PublicServerUrl` +- Configure logging: `RAVEN_Logs_Mode=Operations` (in 7.0+: `RAVEN_Logs_Min_Level=3`) + +Example: + +{CODE-BLOCK:bash} +docker run -p 8080:8080 \ + -e RAVEN_Setup_Mode=None \ + -e RAVEN_Security_UnsecuredAccessAllowed=PrivateNetwork \ + -e RAVEN_Logs_Min_Level=3 \ + ravendb/ravendb:ubuntu-latest +{CODE-BLOCK/} + +For more options, visit this page: [Server Configuration](../../server/configuration) + +#### **Storing data** + +For development purposes, you may want to persist your data. +RavenDB uses the following volumes for persistence and configuration: + +- **Configuration Volume**: `/etc/ravendb` (e.g., settings.json) +- **Data Volume**: `/var/lib/ravendb/data` + +To mount these volumes, use: + +{CODE-BLOCK:bash} +docker run -v /path/to/config:/etc/ravendb \ + -v /path/to/data:/var/lib/ravendb/data \ + ravendb/ravendb:ubuntu-latest +{CODE-BLOCK/} + +To learn about statefullness and storing RavenDB data in a containers, or if you run into trouble, visit Containers > Requirements > Storage documentation page. + +#### **Advanced Networking** +To read more on RavenDB networking containerized environment, go to Containers > Requirements > Networking. + +{PANEL: FAQ} + +**Q: I use Docker Compose or automated installation. How do I disable the setup wizard?** +A: Set the `Setup.Mode` configuration option to `None` like so: + +{CODE-BLOCK:bash} +RAVEN_ARGS='--Setup.Mode=None' +{CODE-BLOCK/} + +**Q: How can I try RavenDB on my local development machine in unsecured mode?** +A: Set the environment variables: + +{CODE-BLOCK:bash} +RAVEN_ARGS='--Setup.Mode=None' +RAVEN_Security_UnsecuredAccessAllowed='PrivateNetwork' +{CODE-BLOCK/} + +**Q: How can I pass command-line arguments through environment variables?** +A: By modifying the `RAVEN_ARGS`, which will pass the arguments to the RavenDB server: + +{CODE-BLOCK:bash} +RAVEN_ARGS='--log-to-console' +{CODE-BLOCK/} + +**Q: Can I view RavenDB logs using the `docker logs` command?** +A: Yes, but you need to enable console logging by setting the following environment variable: + +{CODE-BLOCK:bash} +RAVEN_ARGS='--log-to-console' +{CODE-BLOCK/} + +Additionally, use `RAVEN_Logs_Min_Level` (7.0+) to set more specific desired logging levels. + +Note that enabling logging to the console may impact performance. + +**Q: How do I use a custom configuration file?** +A: Mount the configuration file as a Docker volume and use the `--config-path` argument: + +{CODE-BLOCK:bash} +docker run -v /path/to/settings.json:/etc/ravendb/settings.json \ +-e RAVEN_ARGS='--config-path /etc/ravendb/settings.json' \ +ravendb/ravendb +{CODE-BLOCK/} + +Alternatively, pass the custom `settings.json` content via the `RAVENDB_SETTINGS` environment variable. + +**Q: How can I manage a server running in a container using CLI?** +A: Besides using the RavenDB Studio, you can connect to the RavenDB administration console using the `rvn` utility: + +{CODE-BLOCK:bash} +docker exec -it CONTAINER_ID /var/lib/ravendb/Server/rvn admin-channel +{CODE-BLOCK/} + +This will connect you to the RavenDB admin console, where you can manage the server interactively. + +{PANEL/} + +--- diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/overview.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/overview.markdown new file mode 100644 index 0000000000..e5a7f677e1 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/overview.markdown @@ -0,0 +1,121 @@ +# Overview of Containers & RavenDB + +## Introduction + +RavenDB is a NoSQL database built for performance, simplicity, and ease of use. It integrates seamlessly with containerized environments, enabling stable and efficient deployments. While running our database in a containerized environment offers numerous benefits, it also comes with challenges, such as managing data persistence and ensuring secure networking. + +This guide provides a comprehensive overview of running RavenDB in containers. It summarizes key concepts, outlines requirements, and highlights the advantages of containerized setups. Additionally, it serves as a hub of knowledge, linking to detailed documentation, guides, and articles to help you navigate every aspect of deploying RavenDB in containerized environments. + +## Contents + +1. [Core Concepts & Difficulties](#core-concepts) +2. [What We Offer](#what-we-offer) +3. [What We Require](#what-we-require) +4. [Benefits](#benefits) + +--- + +## 1. Core concepts + +#### Containers +Containers encapsulate RavenDB and its dependencies for consistent behavior across environments. A containerized setup bundles the runtime, libraries, and configurations necessary for RavenDB operations into a single isolated unit. This isolation ensures that RavenDB functions reliably regardless of variations in the host operating system or underlying hardware. + +While virtual machines also provide isolation, they achieve it by replicating entire operating systems, which introduces significant overhead. Containers, by contrast, leverage the shared kernel architecture, using the host OS kernel to create isolated environments without duplicating the operating system. This approach makes containers inherently lightweight, efficient, and scalable. Other secondary concepts, like container storage and networking, enable this primary design, enhancing practicality while maintaining performance advantages over traditional VMs. + +#### Orchestration +Most systems depend on multiple applications and technologies that must work together effectively to serve the end user. Container technology simplifies this by allowing multiple applications to run in isolated environments (containers), but manual deployment and management of all applications separately can become a challenge. + +The orchestration simplifies the deployment and maintenance of systems built using multiple containers - it combines all containerized apps into a preconfigured and hardened definition. This definition describes the ideal state of the system, including application configurations, storage, networking, security measures, and scalability. This way is called the declarative approach. The developer describes the system (usually by writing a .yaml file) and supplies the orchestrator with it. Orchestrator acknowledges the definition and starts working - it deploys the described system and manages it to keep it working exactly like that. + +Orchestrators also simplify cluster scaling by design and enable self-healing by automatically recovering application containers across available nodes (instances or machines). + + +{PANEL: Difficulties} + +Hosting a database in containerized environment brings many difficulties and challenges, that developers need to face. + +#### Statefulness in a Stateless World +Containers are inherently stateless and designed to be ephemeral, but RavenDB, as a database, requires durable storage for its data. + +This dichotomy introduces challenges like data persistence—storage backends, such as AWS EBS, Azure Disk, or on-premise NFS, which must be properly configured or integrated with the orchestration platform. + +#### Security & Networking +Proper network setup is necessary for secure and reliable communication between RavenDB nodes since RavenDB defines a Cluster differently. +Each Node is a fully independent entity rather than just a "replica." +This design involves a couple of quirks that need addressing. + +This independence enhances resiliency but requires solid configuration to maintain consistent and secure communication across the cluster. + +#### Orchestrator Complexity +Orchestration platforms simplify container management but can complicate troubleshooting. +The network setup can obscure communication paths, making identifying issues like latency or misconfigurations difficult. +Containerized RavenDB instances may be challenging to analyze without direct access due to security limitations on Docker images. + +This security detail restricts traditional debugging tools and complicates problem resolution. +It sometimes requires the usage of container host tooling, which can be not sufficient or even available in serverless regime. +Effective management of RavenDB in such environments requires a solid understanding of the database and the orchestration platform. +{PANEL/} + + +## 2. What We Offer + +In the matter of deploying containers, aside from Server features, we explicitly offer + +#### Official Docker Images +Official RavenDB images for: + +- Ubuntu & Windows Nanoserver - [Dockerhub](https://hub.docker.com/r/ravendb/ravendb/) +- Security Hardened RedHat UBI - [IronBank](https://repo1.dso.mil/dsop/opensource/ravendb/ravendb) + +#### Helm Chart of Secured RavenDB Cluster +Automatic RavenDB cluster deployment in Kubernetes. + +- [ArtifactHub](https://artifacthub.io/packages/helm/ravendb-cluster/ravendb-cluster) +- [GitHub](https://github.com/ravendb/helm-charts) + +#### Deployment Articles & Guides +Step-by-step guides for containerized and orchestrated setups - [Visit Articles Page](https://ravendb.net/articles) + +#### Containers Knowledge Base +Detailed documentation of hosting RavenDB in container environments - [Containers Documentation](.) + +#### Technical Support +Professional & community support scoped at deploying RavenDB in containers - [Support Page](https://ravendb.net/support) + +--- + +## 3. What We Require + +#### Container Runtime +Docker, Podman, containerd or an equivalent. + +#### Compute +Sufficient memory & CPU. Either on-premise or cloud solutions. See [Containers > Requirements > Compute](./requirements/compute). + +#### Networking Configuration +Proper communication between nodes and ingress management. See article [Containers > Requirements > Networking](./requirements/networking). + +#### Persistent Storage +Configure volumes to retain database data across container restarts. See the article [Containers > Requirements > Storage](./requirements/storage). + +#### Security +Depending on your solution, you'll need SSL/TLS certificates, role-based access control (RBAC), or other methods for secure deployment. See the article [Containers > Requirements > Security](./requirements/security). + +## 4. Benefits +### a. Containers +#### Consistency +Containers ensure a uniform environment across development, staging, and production, eliminating the "it works on my machine" problem. + +#### Isolation +Containers provide an isolated environment for the application. Thus, there's no need to plan strategy of environment sharing between applications. + +#### Lightweight +Containers share the host's kernel, reducing overhead, improving resource efficiency, and keeping processes separate. + + +### b. Orchestration +#### Declarative Management +Tools like Kubernetes enable you to define the desired system state through YAML files, such as application configuration, nodes, resource allocation, security, and networking. The orchestrator ensures the system maintains this state automatically. + +#### High Availability +Orchestration platforms distribute RavenDB nodes across multiple machines or regions, ensuring resilience against hardware failures. Automatic failover mechanisms keep your database accessible even when a node goes offline. diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/.docs.json b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/.docs.json new file mode 100644 index 0000000000..5dcb030f0c --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/.docs.json @@ -0,0 +1,34 @@ +[ + { + "Path": "compute.markdown", + "Name": "Compute", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + + { + "Path": "licensing.markdown", + "Name": "Licensing", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + + { + "Path": "networking.markdown", + "Name": "Networking", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + { + "Path": "security.markdown", + "Name": "Security", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + }, + { + "Path": "storage.markdown", + "Name": "Storage", + "DiscussionId": "72d5af53-f78e-4af6-8113-e3c58f40a6b4", + "Mappings": [] + } +] diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/compute.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/compute.markdown new file mode 100644 index 0000000000..a9f7e0df67 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/compute.markdown @@ -0,0 +1,57 @@ +# Computing Requirements for RavenDB in Containers + +Whether you're deploying on-premises, in virtual machines, or in managed Kubernetes environments, understanding the computing requirements is key to ensuring smooth operation. + +## **Container Runtime** + +RavenDB requires a container runtime capable of running the Docker image. This includes common runtimes such as: + +- Docker +- Podman +- containerd + +Ensure your runtime supports the architecture and platform for your deployment. + +## **Machine Requirements** + +To achieve optimal performance, allocate resources according to your workload: + +- **CPU:** + A minimum of 2 cores is required for basic setups. For medium workloads, allocate at least 4 cores. +- **Memory:** + At least 1 GB of RAM is essential for minimal setups. If additional memory is needed, consider using `swap` as an alternative for super-minimal setups. +- **Storage:** + SSDs are recommended for low-latency I/O operations. Ensure sufficient capacity to accommodate your database size, along with extra space for indexing and backups. + + +## **Deployment Options** + +#### On-Premise machines +Deploy RavenDB containers on **your physical servers**. +It provides full control over your hardware and networking. +It's suitable for environments with existing infrastructure. + +All you need is one of the container runtimes, and a kernel. + +#### Virtual Machines (VMs) +**Cloud-based or self-hosted VMs**. It's scalable and flexible, while maintaining control over resources. +AWS EC2, Azure Virtual Machines, or private data centers. + +#### Kubernetes +Run RavenDB in managed Kubernetes clusters to simplify container orchestration and scalability. +This option supports dynamic workloads with features like autoscaling and node group management. + +You should be able to deploy a **node group** to match your computing needs. Many providers are offering such service - EKS, AKS, GKE, etc. +Kubernetes always increases the cost of a solution by far, but the power it offers is often unmatched. + +--- + +## **ARM Architecture Support** + +RavenDB supports **ARM64**, allowing deployments on cost-efficient architectures. + +- AWS Graviton instances. +- Azure Ampere-based virtual machines. +- Google Cloud Tau T2A instances. + +The official RavenDB Docker image is compatible with both **x64** and **ARM64**, ensuring broad support across modern hardware. diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/licensing.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/licensing.markdown new file mode 100644 index 0000000000..6a3da8c9f7 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/licensing.markdown @@ -0,0 +1,21 @@ +# Licensing Requirements for RavenDB in Containers + +When running your database in a containerized or orchestrated environment, ensuring **RavenDB can access its license** is a necessary but straightforward step. Compared to more complex matters like managing persistent storage, securing networking, or optimizing system performance, licensing is one of the simplest tasks to configure. + +For developers and DevOps teams, this involves making the license accessible to the database using methods such as configuration settings, environment variables, or secure solutions like secret vaults. The key is to provide the license to the server while maintaining its security. +Common problems include passing the JSON license through to the container - **escaping, quotes, slashes**. +You need to ensure that. + +##### Simplify License Formatting with jq +To ensure the license is properly formatted, use the following command: +``` +jq -c '.' license.json > formatted-license.json +``` + +This command reads the license.json file, formats it into a single-line JSON string suitable for environment variables or configuration files, and saves it to formatted-license.json. + +------ + +In most cases, using an environment variable is sufficient, especially in isolated or development environments. For production or sensitive setups, a secret vault can further enhance security. Regardless of the method, the container must have consistent access to the license. + +For **detailed guidance** on licensing RavenDB in containerized environments, including examples, **refer to our documentation**: [Licensing RavenDB in Docker](../../licensing/license-under-docker). diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/networking.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/networking.markdown new file mode 100644 index 0000000000..ef8dc5cfd7 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/networking.markdown @@ -0,0 +1,73 @@ +# Networking Requirements for Running RavenDB in Containers + +## **Overview** + +Networking is a critical aspect of running RavenDB in containers. +As a database that relies on both HTTP and TCP protocols for communication, +proper network configuration is essential to ensure healthy cluster node-to-node communication and client connectivity. +This article outlines the specific networking requirements and configurations for RavenDB in containerized environments. + +--- + +## **Key Networking Concepts for RavenDB** + +#### Ports Used by RavenDB + +- **HTTP Port:** Used for client communication, management, and the RavenDB Studio. Default is `8080`. In production, RavenDB should use secured, certificate-backed connection (HTTPS). +- **TCP Port:** Used for cluster communication between nodes. Default is `38888`. + +Both ports must be properly exposed and accessible for RavenDB to function correctly, especially in a cluster setup. +Additionally, RavenDB must be able to **reach itself** e.g. for cluster health checks. + + +#### Cluster Communication + +- RavenDB nodes within a cluster use both HTTP and TCP ports to perform clustering and replication. See more here: [Clustering Overview](../../../server/clustering/overview) +- It is crucial that traffic between these ports can flow freely across all nodes in the cluster. + +#### PublicServerUrl + +- In containerized environments, `RAVEN_ServerUrl` should point at the network interface bound to the container itself. While this is sufficient for internal communication, external clients and nodes cannot access this address. +- The `RAVEN_PublicServerUrl` must be set to a **DNS name**, **public-facing IP**, or **routing mechanism** (e.g., load balancer or proxy) that directs traffic to the RavenDB container. This ensures external traffic can properly reach the RavenDB instance. + +**Common Issue**: Setting `RAVEN_PublicServerUrl` to `127.0.0.1` can cause confusion and connectivity problems. +In containerized environments, **`127.0.0.1` refers to the loopback address inside the container, not the host machine**. +This mismatch often leads to connectivity issues for external clients or nodes. + + +## **Networking Configuration for Containers** + +#### Expose the server ports + +Ensure both server ports are exposed and accessible internally. +Check firewall rules, security groups, port-forwarding configuration, network policies - anything that can interrupt the network buzz, depending on your setup. +Depending on your container runtime (e.g., Docker, Kubernetes), configure the ports to be published or mapped to the host machine or external network. + +#### Configure PublicServerUrl + +For external traffic, set `RAVEN_PublicServerUrl` to match the network visibility you require: + +- For **LAN** access: Use the machine’s LAN IP (e.g., 192.168.x.x) and ensure it is reachable by other devices on the local network. +- For **external internet** access: Use a public-facing DNS name or IP address, often routed via a load balancer or reverse proxy. +- For localhost **testing** only: Use the loopback address (127.0.0.1), but note that this will restrict access to clients on the same container. + +**Important Note**: The address set in RAVEN_PublicServerUrl determines how other systems (e.g., clients, other nodes, or users) perceive and reach the server. Ensure it aligns with your intended deployment network. + +#### Ensure node-to-node communication + +Nodes in a RavenDB cluster must communicate over both HTTP and TCP ports. +Networking configurations should allow unrestricted traffic flow between nodes to maintain cluster health. + +#### Ensure client communication + +Make sure your client traffic (including RavenDB Studio) reaches the server correctly. + +On local networks, ensure the DNS or IP address provided in RAVEN_PublicServerUrl resolves correctly within the LAN. + +On public networks, a load balancer or reverse proxy should direct traffic to the container. Using an internet-facing IP, DNS name, load balancer, reverse proxy or other mechanism, ensure consistent routing to the container. + +#### Secure Communication +Use encryption (TLS/SSL) to secure the payload, especially when exposing RavenDB to public networks. +See more in [Requirements > Security](./security) + + diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/security.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/security.markdown new file mode 100644 index 0000000000..d205a803fb --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/security.markdown @@ -0,0 +1,70 @@ +# Certificates & Renewal requirements for Running RavenDB in Containers + + +## **Overview** + +After networking works properly [Containers > Requirements > Networking](./networking), let's focus on reliable and secure communication requirements. +RavenDB uses X.509 certificate-based authentication [Security Overview](../../../server/security/overview) for secured connection. + + +This documentation page will describe the crucial aspects of using certificates while running RavenDB in containers. + +## Getting the certificate +#### Setup Wizard +You can use the `Setup.Mode: Initial` configuration option to run the Setup Wizard if you need it. It can generate the LetsEncrypt certificate for you, create a setup package for your other nodes, and more. +Check what it's fully capable of here: [Setup Wizard Docs](../../installation/setup-wizard) + +Setup Wizard will be a no-go for you in some containerized or orchestrated setups because of the quirks of containerized (stateless) or declarative world. +Fortunately, RavenDB is aware of that and provides many different ways to handle it, like certificate management script injection, to cover your case. + + +#### Generate it on your own +If you need to generate it on your own behalf, you'll need to generate the .pfx certificate yourself (e.g., using OpenSSL or tools like certbot that talk to LetsEncrypt). +After getting your cert, start tuning the server to leverage it for security. + +## Providing a certificate +RavenDB needs to get its server certificate. You can configure its retrieval from one of these origins: +- Path - A .pfx certificate stored under a path reachable for a container. + **Security.Certificate.Path** configuration option value defines the path. [Security Configuration - Security.Certificate.Path](../../../server/configuration/security-configuration#security.certificate.path). + +- Script - A script that returns your certificate by any means. + You can obtain it from container environmental variables, secured vault, secret, etc. + **Security.Certificate.Load.Exec** configuration option value defines the script path. [Security Configuration - Security.Certificate.Load.Exec](../../../server/configuration/security-configuration#security.certificate.load.exec). + +These configuration options can be passed to RavenDB by settings.json, environmental variables, or command line arguments. +See more here: [Configuration Options](../../../server/configuration/configuration-options) + +This way, RavenDB should be able to get its certificate. + +## Certificate expiration +Expired certificates should be updated and replaced. + +#### LetsEncrypt - Setup Wizard +LetsEncrypt certificate management automation allows RavenDB to refresh your LetsEncrypt certificate automatically. +To enable it, set `Setup.Mode` configuration option to `LetsEncrypt`. +Be aware that this automation will work **only when using Setup Wizard to obtain the LetsEncrypt certificate**, as RavenDB doesn't control your domain nor can access your backend used in the certificate load script. +To learn more about this, visit this site: [RavenDB Lets Encrypt Certificates Docs](../../../server/security/authentication/lets-encrypt-certificates) + +You can learn about different `Raven.SetupMode` values here: [Core Configuration - Setup.Mode](../../../server/configuration/core-configuration#setup.mode) +Also, you need to provide us with an email that you will use for the Let's Encrypt matter. Use `Security.Certificate.LetsEncrypt.Email`. + +#### Manual +To configure manual certificate replacement and updates, write scripts to supply RavenDB configuration: +- [Security.Certificate.Renew.Exec](../../../server/configuration/security-configuration#security.certificate.renew.exec) +- [Security.Certificate.Change.Exec](../../../server/configuration/security-configuration#security.certificate.change.exec) + +It will allow RavenDB to execute your routines, which should: + +- check if the certificate is ready to renew and do so if needed, then return it (**Renew**) +- replace the old certificate (**Change**) + +To learn about manual certificate replacement, read this article: [Certificate Renewal And Rotation](../../../server/security/authentication/certificate-renewal-and-rotation) + + +### Conclusion +Some of these approaches may not apply in your containerized case, especially when storing your certificates in a secured vault. +Be careful and pick the way of handling certificates that suits your case the best. +A good rule of thumb is to pick the least complex solution that works for you. +The easiest is to rely on the automatic renewal provided by RavenDB. +Writing your own scripts for getting, updating, and replacing certificates may require more effort but may also suit you better. + diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/storage.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/storage.markdown new file mode 100644 index 0000000000..b4d69db152 --- /dev/null +++ b/Documentation/6.0/Raven.Documentation.Pages/start/containers/requirements/storage.markdown @@ -0,0 +1,43 @@ +# Storage Requirements for Running RavenDB in Containers + +## **Overview** + +RavenDB is a *database*, and requires reliable and durable storage for its data. +This article focuses on describing the storage needs for **containerized environments**, +addressing the unique challenges and requirements of running RavenDB in containers. +Containers, being stateless, require robust storage configurations to persist RavenDB data across container restarts, upgrades, or failures. + +If you are looking for a broader understanding of RavenDB's storage mechanisms, please refer to the following articles: + +- [Storage Engine](../../../server/storage/storage-engine) +- [Directory Structure](../../../server/storage/directory-structure) + +--- + +## **Why Storage Matters for RavenDB Containers** + +Containers encapsulate applications for consistency and portability but lack built-in mechanisms for persisting data. +As a database, RavenDB must store its data in a **persistent volume** or an equivalent storage solution to survive the ephemeral nature of containers. +Without proper configuration: + +- Data will be lost if the container is restarted or replaced. +- Performance may degrade due to suboptimal storage setups. +- Inconsistent behavior can arise during scaling, updates or failover operations. + +--- + +## **Requirements** + +1. **Volume Configuration** + - RavenDB requires a volume (or equivalent storage backend) to store its data files, journals, and indexes. + - The volume must be explicitly mounted into the container and made accessible to the `ravendb` process. + +2. **Permissions** + - The container runs with the `ravendb` user (`UID:GID 999:999`). + - Ensure the mounted storage has the correct read/write permissions for the `ravendb` user. + - If you're using volume, that is a slice of already-existing file system, the original file system needs to already have correct permissions set for `ravendb (999:999)`. + +3. **Storage Backend Options for Containers** + - Host-mounted volumes + - Managed storage services like AWS EBS, Azure Disk, or Google Persistent Disks + diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/getting-started.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/getting-started.markdown index 017e0470d8..4ba3dd640c 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/start/getting-started.markdown +++ b/Documentation/6.0/Raven.Documentation.Pages/start/getting-started.markdown @@ -101,7 +101,7 @@ machine restarts), this simple step will be done after initial secure installati {NOTE: Running in a Docker container} -If you are interested in hosting the server in a Docker container, please read our [dedicated article](../start/installation/running-in-docker-container). +If you are interested in hosting the server in a Docker container, please read our [dedicated knowledge base](../start/containers/overview). {NOTE/} @@ -111,7 +111,6 @@ If you are interested in hosting the server on a VM, please refer to - [AWS Windows VM](../start/installation/setup-examples/aws-windows-vm) - [AWS Linux VM](../start/installation/setup-examples/aws-linux-vm) -- [Docker on AWS Linux VM](../start/installation/setup-examples/aws-docker-linux-vm) {NOTE/} @@ -332,7 +331,7 @@ select Name ### Installation - [Setup Wizard](../start/installation/setup-wizard) - [System Requirements](../start/installation/system-requirements) -- [Running in a Docker Container](../start/installation/running-in-docker-container) +- [Running in a Container](../start/containers/overview) ### Session - [Introduction](../client-api/session/what-is-a-session-and-how-does-it-work) diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/installation/.docs.json b/Documentation/6.0/Raven.Documentation.Pages/start/installation/.docs.json index e6f8b50082..02f7a6ce55 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/start/installation/.docs.json +++ b/Documentation/6.0/Raven.Documentation.Pages/start/installation/.docs.json @@ -28,12 +28,6 @@ "DiscussionId": "f40e088f-6317-4bb2-8df6-87a2523fd452", "Mappings": [] }, - { - "Path": "running-in-docker-container.markdown", - "Name": "Running in a Docker Container", - "DiscussionId": "eda38daa-a361-4114-9519-0684a7e1bda2", - "Mappings": [] - }, { "Path": "upgrading-to-new-version.markdown", "Name": "Upgrading to a New Version", diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown deleted file mode 100644 index cfe59c8d1b..0000000000 --- a/Documentation/6.0/Raven.Documentation.Pages/start/installation/running-in-docker-container.markdown +++ /dev/null @@ -1,287 +0,0 @@ -# Installation: Running in a Docker Container ---- - -{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 - [dockerhub](https://hub.docker.com/r/ravendb/ravendb/) page. -* 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) - * [Setup and Execution](../../start/installation/running-in-docker-container#setup-and-execution) - * [Migration](../../start/installation/running-in-docker-container#migration) - * [Configuration](../../start/installation/running-in-docker-container#configuration) - * [FAQ](../../start/installation/running-in-docker-container#faq) - - -{NOTE/} - ---- - -{PANEL: Requirements} - -* **Docker Configuration** - Use the default Docker networking configuration. -* **Security** - Do not expose the Docker instance beyond the host machine. - {WARNING: } - If you Do intend to host RavenDB on Docker and expose it - externally, please make sure the server is [secure](../../start/installation/setup-wizard#secure-setup-with-a-free-let). - {WARNING/} -* **Storage** - * Non-NFS file systems **are** Supported. - NTFS, Ext4, and other non-NFS volume mounts' file systems are supported. - * SMB and CIFS mounts are **not** supported. - Linux Docker containers running under Windows Docker hosts via shared volumes - are [not supported](../../start/installation/deployment-considerations#storage-considerations) - due to CIFS protocol usage. -* **Platforms** - RavenDB images are available for: - * **Ubuntu** (22.04, 20.04) or any other Debian-based distribution. - * [Windows Nano Server](https://hub.docker.com/_/microsoft-windows-nanoserver) - -{PANEL/} - -{PANEL: Setup and Execution} - -#### RavenDB Versions -To install or run a Docker RavenDB image use an updated **stable** or **nightly** version. - -* [Stable and LTS images](https://hub.docker.com/r/ravendb/ravendb/) -* [Nightly releases](https://hub.docker.com/r/ravendb/ravendb-nightly/) - ---- - -#### Available Image Tags -Use the following tags to install the latest **Stable** or **LTS** RavenDB Server version. - -* **Latest RavenDB version** - * _Tag_: `latest` / `ubuntu-latest` - Latest RavenDB version, running on Ubuntu container - * _Tag_: `windows-latest` - Latest RavenDB version, running on Windows Nano Server - * _Tag_: `windows-1809-latest` - Latest RavenDB version, running on Windows Nano Server version 1809 - * _Tag_: `windows-ltsc2022-latest` - Latest RavenDB version, running on Windows Nano Server version LTSC2022 - * An updated tags list is available [here](https://github.com/ravendb/ravendb/blob/v6.0/docker/readme.md#latest-stable). - -* **Latest RavenDB LTS version** - * _Tag_: `latest-lts` / `ubuntu-latest-lts` - Latest RavenDB LTS version, running on Ubuntu container - * _Tag_: `windows-latest-lts` - Latest RavenDB LTS version, running on Windows Nano Server - * _Tag_: `windows-1809-latest-lts` - Latest RavenDB LTS version, running on Windows Nano Server version 1809 - * _Tag_: `windows-ltsc2022-latest-lts` - Latest RavenDB LTS version, running on Windows Nano Server version LTSC2022 - * An updated tags list is available [here](https://github.com/ravendb/ravendb/blob/v6.0/docker/readme.md#latest-lts) - ---- - -#### Running a RavenDB image -To install or run RavenDB start the Docker service, and run a RavenDB image manually or using a script. - -* **Running manually**: - Run RavenDB using [docker run](https://docs.docker.com/engine/reference/commandline/run/), e.g. - - _Ubuntu image_: `$ docker run -p 8080:8080 ravendb/ravendb:ubuntu-latest` - _Windows image_: `$ docker run -p 8080:8080 ravendb/ravendb:windows-latest` - -* **Running using a script:** - Run a RavenDB image using a dedicated script for Ubuntu or Windows. - [Ubuntu-based image script](https://github.com/ravendb/ravendb/blob/v5.4/docker/run-linux.ps1) - [Windows-based image script](https://github.com/ravendb/ravendb/blob/v5.4/docker/run-nanoserver.ps1) - -{NOTE: Setup and Management} -After running the image, access it from a browser using its URL. -By default: `http://localhost:8080` - -If the server is not installed yet, connecting it will start the Setup Wizard. -After installing the server, connecting it will open its [management studio](https://ravendb.net/docs/article-page/latest/csharp/studio/overview). -{NOTE/} - ---- - -#### Sharing data with Docker Host -To share data with the Docker host using Docker for Windows: - -* The Docker client application must have `sharing` enabled. -* The directory (e.g. `C:\RavenDb\Data`) must exist. - ---- - -#### Dockerfiles -The `Dockerfiles` used to build RavenDB Server images and their assets can be found at: - -* [Ubuntu image Dockerfile](https://github.com/ravendb/ravendb/tree/v6.0/docker/ravendb-ubuntu) -* [Windows Nano Server image Dockerfile](https://github.com/ravendb/ravendb/tree/v6.0/docker/ravendb-nanoserver) - ---- - -#### Persisting Data - -To install using the `latest` tag, and persist the data stored on your -hard disk if the container is removed, you can use: -{CODE-BLOCK:bash} -docker run --rm -d -p 8080:8080 -p 38888:38888 -v /var/lib/ravendb/data ravendb/ravendb -{CODE-BLOCK/} - -* The data will now remain available even if the container is removed. -* When you start a new instance of the image using a volume mounted to - the same directory, the data will still be available. -* To keep persistence, RavenDB data in a Windows container is always - kept in this location: `C:/RavenDB/Server/RavenData` - ---- - -#### Skipping the Setup Wizard -To start the RavenDB container on your localhost without running -through the Setup Wizard each time, you can use: -{CODE-BLOCK:bash} -docker run --rm -d -p 8080:8080 -p 38888:38888 -v /var/lib/ravendb/data --name RavenDb-WithData --e RAVEN_Setup_Mode=None -e RAVEN_License_Eula_Accepted=true --e RAVEN_Security_UnsecuredAccessAllowed=PrivateNetwork ravendb/ravendb -{CODE-BLOCK/} - -Using this command will skip the Setup Wizard and mount a volume for data persistence. - -{WARNING: Warning} -Please be aware that running a Docker container with `RAVEN_Setup_Mode=None` and -`RAVEN_Security_UnsecuredAccessAllowed=PrivateNetwork` will run an **Unsecure** server. -{WARNING/} - -{INFO: EULA acceptance} -By setting `RAVEN_License_Eula_Accepted=true` you're accepting our [terms & conditions](https://ravendb.net/terms/commercial). -{INFO/} - -{PANEL/} - -{PANEL: Migration} - -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/} - -{PANEL: Configuration} -RavenDB can be adjusted using: - -* The [settings.json](../../server/configuration/configuration-options#settings.json) configuration file. - -* [Environment Variables](../../server/configuration/configuration-options#environment-variables), e.g. - - {CODE-BLOCK:plain} - RAVEN_Setup_Mode=None -RAVEN_DataDir=RavenData -RAVEN_Certificate_Path=/config/raven-server.certificate.pfx - {CODE-BLOCK/} - -* [CLI arguments](../../server/configuration/configuration-options#command-line-arguments) - Variables can be passed to a RavenDB Docker image in a CLI arguments line, e.g. - - `./Raven.Server --Setup.Mode=None` - -{PANEL/} - -{PANEL: FAQ} - -#### Q: I use `compose` or run an automated installation. How do I disable the setup wizard? -**A:** Set the `Setup.Mode` configuration option to `None`m like so: -{CODE-BLOCK:plain} -RAVEN_ARGS='--Setup.Mode=None' -{CODE-BLOCK/} - ---- - -#### Q: I want to try RavenDB on my local / development machine. How do I run an unsecure server? -**A:** Set the env variables like so: -{CODE-BLOCK:plain} -RAVEN_ARGS='--Setup.Mode=None' -RAVEN_Security_UnsecuredAccessAllowed='PrivateNetwork' -{CODE-BLOCK/} - ---- - -#### Q: How can I pass command line arguments? -**A:** By modifying `RAVEN_ARGS` environment variables, -that will be passed on as a CLI arguments line. - ---- - -#### Q: Can I see RavenDB logs in container logs? -**A:** To get logs available when running the `docker logs` command, you need to enable -this option in RavenDB server. -E.g., set the environment variables as shown below to enable logging to the console. -{CODE-BLOCK:plain} -RAVEN_ARGS='--log-to-console' -{CODE-BLOCK/} - -{NOTE: } -Please note that this behavior may have performance implications. -To modify the logging level use the `RAVEN_Logs_Mode` variable. - -Additional information regarding logging configuration is available -[here](../../server/configuration/logs-configuration). -{NOTE/} - ---- - -#### Q: How do I use a custom config file? -**A:** Mount it as a Docker volume, and use the `--config-path PATH_TO_CONFIG` -command line argument to use a settings file from outside of the server directory. -Alternatively, you can pass your custom `settings.json` content via the -`RAVENDB_SETTINGS` environment variable. - ---- - -#### Q: How can I manage server running in a container? -**A:** Except for the RavenDB Studio, which can be accessed from the browser, -you can connect the RavenDB administration console using the `rvn` utility -as follows: -{CODE-BLOCK:plain} -> docker exec -it CONTAINER_ID /opt/RavenDB/Server/rvn admin-channel -Will try to connect to discovered Raven.Server process : 8... - - _____ _____ ____ - | __ \ | __ \| _ \ - | |__) |__ ___ _____ _ __ | | | | |_) | - | _ // _` \ \ / / _ \ '_ \| | | | _ < - | | \ \ (_| |\ V / __/ | | | |__| | |_) | - |_| \_\__,_| \_/ \___|_| |_|_____/|____/ - - - Safe by default, optimized for efficiency - - Build 60, Version 6.0, SemVer 6.0.0-custom-60, Commit 10ed5a8 - PID 8232, 64 bits, 8 Cores, Phys Mem 23.866 GBytes, Arch: X64 - Source Code (git repo): https://github.com/ravendb/ravendb - Built with love by Hibernating Rhinos and awesome contributors! -+---------------------------------------------------------------+ -Connected to RavenDB Console through named pipe connection... - -ravendb> help -... -{CODE-BLOCK/} - -{NOTE: } -Additional information about running RavenDB as a console is available -[here](../../server/administration/cli). -{NOTE/} - -{PANEL/} - -## Related Articles - -### Installation -- [Running as a Service](../../start/installation/running-as-service) -- [Upgrading to New Version](../../start/installation/upgrading-to-new-version) - -### Setup Examples -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) diff --git a/Documentation/6.0/Raven.Documentation.Pages/start/licensing/license-under-docker.markdown b/Documentation/6.0/Raven.Documentation.Pages/start/licensing/license-under-docker.markdown index d292d1e291..f9abcd2609 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/start/licensing/license-under-docker.markdown +++ b/Documentation/6.0/Raven.Documentation.Pages/start/licensing/license-under-docker.markdown @@ -117,9 +117,7 @@ To license RavenDB under Linux, pass a license **file** rather than a **director ## Related Articles ### Installation -- [Running in a Docker Container](../../start/installation/running-in-docker-container) +- [Running in a Container](../../start/containers/overview) - [Running as a Service](../../start/installation/running-as-service) - [Upgrading to New Version](../../start/installation/upgrading-to-new-version) -### Setup Examples -- [Docker on AWS Linux VM](../../start/installation/setup-examples/aws-docker-linux-vm) diff --git a/Documentation/6.2/Raven.Documentation.Pages/start/installation/.docs.json b/Documentation/6.2/Raven.Documentation.Pages/start/installation/.docs.json index e6f8b50082..02f7a6ce55 100644 --- a/Documentation/6.2/Raven.Documentation.Pages/start/installation/.docs.json +++ b/Documentation/6.2/Raven.Documentation.Pages/start/installation/.docs.json @@ -28,12 +28,6 @@ "DiscussionId": "f40e088f-6317-4bb2-8df6-87a2523fd452", "Mappings": [] }, - { - "Path": "running-in-docker-container.markdown", - "Name": "Running in a Docker Container", - "DiscussionId": "eda38daa-a361-4114-9519-0684a7e1bda2", - "Mappings": [] - }, { "Path": "upgrading-to-new-version.markdown", "Name": "Upgrading to a New Version", diff --git a/Documentation/7.0/Raven.Documentation.Pages/start/installation/.docs.json b/Documentation/7.0/Raven.Documentation.Pages/start/installation/.docs.json index e6f8b50082..02f7a6ce55 100644 --- a/Documentation/7.0/Raven.Documentation.Pages/start/installation/.docs.json +++ b/Documentation/7.0/Raven.Documentation.Pages/start/installation/.docs.json @@ -28,12 +28,6 @@ "DiscussionId": "f40e088f-6317-4bb2-8df6-87a2523fd452", "Mappings": [] }, - { - "Path": "running-in-docker-container.markdown", - "Name": "Running in a Docker Container", - "DiscussionId": "eda38daa-a361-4114-9519-0684a7e1bda2", - "Mappings": [] - }, { "Path": "upgrading-to-new-version.markdown", "Name": "Upgrading to a New Version",