Skip to content

Commit

Permalink
Melissa/db related updates (#534)
Browse files Browse the repository at this point in the history 
* Document volume alerting webhook

* postgres page

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* finish final sections in postgres

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* updates to pg

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* mysql mostly done

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* mongo done mostly

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* redis mostly done

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* pg ready for review

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* mysql ready for review

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* redis rdy for review

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* mongo rdy for review

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

* add banner and polish

Signed-off-by: Melissa Hale <melissakayh@gmail.com>

---------

Signed-off-by: Melissa Hale <melissakayh@gmail.com>
Co-authored-by: Paulo Cabral <paulosanz@poli.ufrj.br>
  • Loading branch information
@melissa-hale @paulocsanz
melissa-hale and paulocsanz authored Aug 16, 2024
1 parent 284f6e3 commit 6b15e14
Show file tree
Hide file tree
Showing 4 changed files with 403 additions and 57 deletions.
105 changes: 92 additions & 13 deletions src/docs/guides/mongodb.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,36 @@
---
title: MongoDB
title: Deploy MongoDB
---

The Railway MongoDB database service allows you to provision and connect to a
MongoDB database with zero configuration.
Railway offers two MongoDB deployment options to accommodate different needs: a **Standalone Instance** and a **High Availability (HA) Replica Set**.

- **Standalone Instance** - a single MongoDB database server that is easy to manage; ideal for development environments, smaller projects, or services that are less sensitive to disruption.

- **High Availability (HA) Replica Set** - intended for production workloads where uptime is critical. It consists of three MongoDB nodes configured as a [replica set](https://www.mongodb.com/docs/manual/replication/).

## Standalone MongoDB

Let's talk about how to deploy, connect, and manage the standalone instance.

## Deploy

Add a MongoDB database to your project via the `CMD + K` menu or by clicking the `+ New` button on the Project Canvas.
You can deploy a standalone MongoDB database via the `CMD + K` menu or by clicking the `+ New` button on the Project Canvas.

<Image src="https://res.cloudinary.com/railway/image/upload/v1695934218/docs/databases/addDB_qxyctn.gif"
alt="GIF of the Adding Database"
layout="intrinsic"
layout="responsive"
width={450} height={396} quality={100} />

You can also deploy it via the [template](https://railway.app/template/mongodb) from the template marketplace.

#### Deployed Service

Upon deployment, you will have a standalone MongoDB service running in your project, deployed from the official [mongo](https://hub.docker.com/_/mongo) Docker image.

#### Custom Start Command

The MongoDB database service starts with the following [Start Command](/deploy/deployments#start-command) to enable communication over [Private Network](/reference/private-networking): `mongod --ipv6 --bind_ip ::,0.0.0.0`

## Connect

Connect to MongoDB from another service in your project by [referencing the environment variables](/guides/variables#referencing-another-services-variable) made available in the Mongo service:
Expand All @@ -24,21 +41,83 @@ Connect to MongoDB from another service in your project by [referencing the envi
- `MONGOPASSWORD`
- `MONGO_URL`

#### Connecting externally
#### Connecting Externally

It is possible to connect to MongoDB externally (from outside of the [project](/develop/projects) in which it is deployed), by using the [TCP Proxy](/deploy/exposing-your-app#tcp-proxying) which is enabled by default.

Keep in mind that you will be billed for [Network Egress](/reference/pricing/plans#resource-usage-pricing) when using the TCP Proxy.
*Keep in mind that you will be billed for [Network Egress](/reference/pricing/plans#resource-usage-pricing) when using the TCP Proxy.*

### Modify the Deployment

## Image
Since the deployed container is pulled from the official [MongoDB](https://hub.docker.com/_/mongo) image in Docker Hub, you can modify the deployment based on the [instructions in Docker Hub](https://hub.docker.com/_/mongo).

The MongoDB database service uses the Docker official [mongo](https://hub.docker.com/_/mongo) image.
## High Availability MongoDB Replica Set

## Custom Start Command
<Banner>
**Released August 2024**

The MongoDB database service starts with the following [Start Command](/deploy/deployments#start-command) to enable communication over [Private Network](/reference/private-networking): `mongod --ipv6 --bind_ip ::,0.0.0.0`
Be aware that this template has been minimally tested. We are actively seeking feedback to improve the experience using this template. Please provide your input [here](https://help.railway.app/templates/mongo-replica-set-948643d5).
</Banner>

We'll cover how to deploy, connect, and manage the [High Availability (HA) MongoDB Replica Set](https://www.mongodb.com/docs/manual/replication/) in this section.

### Deploy

You can deploy a HA MongoDB Replica Set via the [template in the marketplace](https://railway.app/template/ha-mongo).

<Image src="https://res.cloudinary.com/railway/image/upload/v1723605087/docs/databases/CleanShot_2024-08-13_at_21.10.13_2x_xs9enn.png"
alt="MongoDB HA in the marketplace"
layout="responsive"
width={405} height={396} quality={100} />

#### Deployed Services

Upon deployment, a cluster of 3 MongoDB nodes will be added to your project. The nodes are deployed from a [custom Dockerfile](https://github.com/railwayapp-templates/mongo-replica-set/tree/main/nodes). The Dockerfile pulls the [mongo Docker image](https://hub.docker.com/_/mongo) and copies a script into the container. The script is run when the container starts to generate the [keyfile](https://www.mongodb.com/docs/manual/tutorial/deploy-replica-set-with-keyfile-access-control/) for authentication.

An [init service](https://github.com/railwayapp-templates/mongo-replica-set/tree/main/initService) is also deployed alongside the nodes to initiate the replica set once the nodes are up. It should be deleted post-deploy.

#### Multi-region Deployment

By default, each node is deployed to a different region (US West, US East, and EU West) for fault tolerance.

Since region selection is a Pro-only feature, this only applies to Pro users. If you deploy this template as a Hobby user, all nodes will deploy to US West.

### Connect

To connect to the MongoDB Replica Set, you should construct your MongoDB URI to include all nodes in the set. Each node exposes a `REPLICA_SET_PRIVATE_URI` environment variable that can be referenced to connect to the cluster.

<Image src="https://res.cloudinary.com/railway/image/upload/v1723762488/docs/databases/CleanShot_2024-08-15_at_16.53.37_udssxa.gif"
alt="Mongo URI variable"
layout="responsive"
width={655} height={396} quality={100} />

For some examples, check out the [example apps](https://github.com/railwayapp-templates/mongo-replica-set/tree/main/exampleApps) within the source repo for the replica set.

#### Connecting Externally

It is possible to connect to the MongoDB Replica Set externally (from outside of the [project](/develop/projects) in which it is deployed) by using the [TCP Proxy](/deploy/exposing-your-app#tcp-proxying).

*Keep in mind that you will be billed for [Network Egress](/reference/pricing/plans#resource-usage-pricing) when using the TCP Proxy.*

### Modify the Deployment

Since the containers deployed are based on the MongoDB image, you can reference the [documentation in Docker hub](https://hub.docker.com/_/mongo) to understand how to customize them using environment variables.

You can also fork the [Mongo Cluster](https://github.com/railwayapp-templates/mongo-replica-set) repository to make changes not supported by environment variables.

## Backup and Monitoring

Especially for production environments, performing regular backups and monitoring the health of your database is essential. Consider adding:

- **Backup solutions**: Automate regular backups to ensure data recovery in case of failure. We suggest checking out this [Database S3 backups](https://railway.app/template/U_wjYd) template as an example.

- **Observability**: Implement monitoring for insights into performance and health of your database. Check out the tutorial which covers [setting up observability on a Mongo replica set](https://docs.railway.app/tutorials/deploy-and-monitor-mongo#4-set-up-monitoring-of-the-replica-set).

## Additional Resources

While these templates are available for your convenience, they are considered unmanaged, meaning you have total control over their configuration and maintenance.

## Changing System Variables
We *strongly encourage you* to refer to the source documentation to gain deeper understanding of their functionality and how to use them effectively. Here are some links to help you get started:

Tailor your MongoDB service to your needs by adding any variables relevant to the [mongo](https://hub.docker.com/_/mongo) image.
- [Mongo Documentation](https://www.mongodb.com/docs/manual/introduction/)
- [Replication in Mongo](https://www.mongodb.com/docs/manual/replication/)
124 changes: 111 additions & 13 deletions src/docs/guides/mysql.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,33 @@
---
title: MySQL
title: Deploy MySQL
---

The Railway MySQL database service allows you to provision and connect to a
MySQL database with zero configuration.
Railway offers two MySQL deployment options to accommodate different needs: a **Standalone Instance** and a **High Availability (HA) Cluster**.

## Deploy
- **Standalone Instance** - a single MySQL database server that is easy to manage; ideal for development environments, smaller projects, or services which are less sensitive to disruption.

You can add a MySQL database via the `CMD + K` menu or by clicking the `+ New` button on the Project Canvas.
- **High Availability (HA) Cluster** - intended for production workloads where uptime is critical. It consists of three MySQL nodes configured as an [InnoDB Cluster](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-innodb-cluster.html) as well as a [MySQL Router](https://dev.mysql.com/doc/mysql-router/8.0/en/mysql-router-general.html) service for connecting to the cluster.

## Standalone MySQL

Let's talk about how to deploy, connect, and manage the standalone instance.

### Deploy

You can deploy a standalone MySQL database via the `CMD + K` menu or by clicking the `+ New` button on the Project Canvas.

<Image src="https://res.cloudinary.com/railway/image/upload/v1695934218/docs/databases/addDB_qxyctn.gif"
alt="GIF of the Adding Database"
layout="intrinsic"
layout="responsive"
width={450} height={396} quality={100} />

## Connect
You can also deploy it via the [template](https://railway.app/template/mysql) from the template marketplace.

#### Deployed Service

Upon deployment, you will have a standalone MySQL service running in your project, deployed directly from the [mysql Docker image](https://hub.docker.com/_/mysql).

### Connect

Connect to MySQL from another service in your project by [referencing the environment variables](/guides/variables#referencing-another-services-variable) made available in the MySQL service:

Expand All @@ -25,16 +38,101 @@ Connect to MySQL from another service in your project by [referencing the enviro
- `MYSQLDATABASE`
- `MYSQL_URL`

#### Connecting externally
#### Connecting Externally

It is possible to connect to MySQL externally (from outside of the [project](/develop/projects) in which it is deployed), by using the [TCP Proxy](/deploy/exposing-your-app#tcp-proxying) which is enabled by default.

Keep in mind that you will be billed for [Network Egress](/reference/pricing/plans#resource-usage-pricing) when using the TCP Proxy.
*Keep in mind that you will be billed for [Network Egress](/reference/pricing/plans#resource-usage-pricing) when using the TCP Proxy.*

### Modify the Deployment

Since the deployed container is pulled from the official MySQL image in Docker hub, you can modify the deployment based on the [instructions in Docker hub](https://hub.docker.com/_/mysql).

## High Availability MySQL InnoDB Cluster

<Banner>
**Released August 2024**

Be aware that this template has been minimally tested. We are actively seeking feedback to improve the experience using this template. Please provide your input [here](https://help.railway.app/templates/my-sql-inno-db-cluster-6afff85d).
</Banner>

We'll cover how to deploy, connect, and manage the [High Availability (HA) MySQL InnoDB Cluster](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-innodb-cluster.html) in this section.

### Deploy

You can deploy a HA MySQL InnoDB cluster via the [template in the marketplace](https://railway.app/template/ha-mysql).

You will need a [Railway API token](/guides/public-api#creating-a-token) to deploy the service. You will be prompted for your token upon deploying the template.

<Image src="https://res.cloudinary.com/railway/image/upload/v1723603487/docs/databases/mysqlcluster_lumnfh.png"
alt="MySQL HA in the marketplace"
layout="responsive"
width={380} height={396} quality={100} />

#### Deployed Services

Upon deployment, a cluster of 3 MySQL nodes will be added to your project. The nodes are deployed from a [custom Dockerfile](https://github.com/railwayapp-templates/mysql-cluster/tree/main/nodes). The Dockerfile pulls the [mysql Docker image](https://hub.docker.com/_/mysql) and copies a `my.cnf` file into each container, configuring the necessary settings to prep the nodes to join the [InnoDB cluster](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-innodb-cluster.html).

An [initialization service](https://github.com/railwayapp-templates/mysql-cluster/tree/main/initService) is also deployed, which waits for the nodes to come online before initializing the cluster and joining the nodes.

Lastly, a [MySQL Router](https://dev.mysql.com/doc/mysql-router/8.0/en/mysql-router-general.html) service is also deployed, which serves as a proxy to the cluster. This router is built from the [MySQL Router image](https://hub.docker.com/r/mysql/mysql-router).

#### Multi-region Deployment

By default, each node is deployed to a different region (US West, US East, and EU West) for fault tolerance.

Since region selection is a Pro-only feature, this only applies to Pro users. If you deploy this template as a Hobby user, all nodes will deploy to US West.

### Connect

You should connect to the cluster via a proxy service which is aware of all of the cluster nodes. We have included a [MySQL Router](https://dev.mysql.com/doc/mysql-router/8.0/en/mysql-router-general.html) service in the template deployment for this purpose.

<Image src="https://res.cloudinary.com/railway/image/upload/v1723760996/docs/databases/CleanShot_2024-08-15_at_16.28.42_miy2og.gif"
alt="MySQL Router variables"
layout="responsive"
width={655} height={396} quality={100} />

Connect to the cluster via the environment variables provided in the MySQL Router:

- `MYSQL_ROUTER_HOST`
- `MYSQL_ROUTER_PORT`
- `MYSQL_USER`
- `MYSQL_PASSWORD`
- `MYSQL_DB`

For an example, check out the [example app](https://github.com/railwayapp-templates/mysql-cluster/blob/main/exampleApps/python/main.py#L19) in the template's source repo.

#### Connecting Externally

It is possible to connect to the MySQL cluster externally (from outside of the [project](/develop/projects) in which it is deployed), by using the [TCP Proxy](/deploy/exposing-your-app#tcp-proxying).

*Keep in mind that you will be billed for [Network Egress](/reference/pricing/plans#resource-usage-pricing) when using the TCP Proxy.*

### Modify the Deployment

Since the containers deployed are based on MySQL images in Docker hub, you can reference the documentation for each, to understand how to customize them using environment variables.

- [MySQL](https://hub.docker.com/_/mysql)
- [MySQL Router](https://hub.docker.com/r/mysql/mysql-router)

We also encourage you to fork the [MySQL Cluster](https://github.com/railwayapp-templates/mysql-cluster/tree/main) repository to make changes not supported by environment variables.

## Backups and Observability

Especially for production environments, performing regular backups and monitoring the health of your database is essential. Consider adding:

- **Backup solutions**: Automate regular backups to ensure data recovery in case of failure. We suggest checking out this [Database S3 backups](https://railway.app/template/U_wjYd) template as an example.

- **Observability**: Implement monitoring for insights into performance and health of your databases. If you're not already running an observability stack, check out these templates to help you get started building one:
- [Prometheus](https://railway.app/template/KmJatA)
- [Grafana](https://railway.app/template/anURAt)

## Image
## Additional Resources

The MySQL database service uses the [mysql:latest](https://hub.docker.com/_/mysql) docker image.
While these templates are available for your convenience, they are considered unmanaged, meaning you have total control over their configuration and maintenance.

## Changing System Variables
We *strongly encourage you* to refer to the source documentation to gain deeper understanding of their functionality and how to use them effectively. Here are some links to help you get started:

Tailor your MySQL service to your needs by adding any variables relevant to the [mysql](https://hub.docker.com/_/mysql) image.
- [MySQL Documentation](https://dev.mysql.com/doc/relnotes/mysql/8.4/en/)
- [MySQL InnoDB Cluster Documentation](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-innodb-cluster.html)
- [MySQL Router Documentation](https://dev.mysql.com/doc/mysql-router/8.0/en/mysql-router-general.html)
Loading

0 comments on commit 6b15e14

Please sign in to comment.