diff --git a/README.md b/README.md index 810937aff7..701a724acb 100644 --- a/README.md +++ b/README.md @@ -222,6 +222,10 @@ postgres=# select * from t; > ./target/debug/neon_local stop ``` +## Running own installation + +If you are interested in running your own cluster of neon storages and compute, it is described in the following doc: [docs/deployment.md](./docs/deployment.md) + ## Running tests Ensure your dependencies are installed as described [here](https://github.com/neondatabase/neon#dependency-installation-notes). diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000000..0007a2dfc2 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,23 @@ +# Deploying neon on your own + +If you are interested in running neon components in Docker containers, there is a tutorial: https://www.percona.com/blog/using-docker-to-deploy-neon-serverless-postgresql/ + +In this document we describe how to run all components on your own. + +## Components overview + +As described in other docs, there are storage components and compute nodes. All of them are basically binaries listening for one or two ports, communicating between each other and some are reading/writing data to disk. + +![](./media/neon-components.svg) + +_Storage broker_ is an in-memory pub-sub service (see more in [doc](./docs/storage_broker.md)), currently it is required one instance per cluster. It listens on `50051` port (grpc server) and safekeepers and pageservers communicate with it. + +_Safekeepers_ are deployed in a cluster, nodes are discovering each other through storage broker and implementing RAFT-based replication, there are needed at least three nodes for now (see more in [doc](./docs/safekeeper-protocol.md)). They are replicating WAL and writing it to data directory, offloading to remote storage if there is no space left on device. Each server is listening on two ports — one for inter-node communication and WAL, the other for HTTP-management API ([spec](../safekeeper/src/http/openapi_spec.yaml)). + +_Pageservers_ basically maintain postgres disk state, which is modified after writing to WAL and read on reading queries without participation of safekeepers. Pageservers can be spowned and stopped based on demand, as long as all the tenants are relocated correspondingly (relocated to alive pageserver before stopping). Service is listening on two ports — one for read/write requests from safekeepers and compute nodes, the other port is for management API (like detaching/attachning tenants, see more in [spec](../pageserver/src/http/openapi_spec.yml)). Data is stored in data directory and offloaded to the remote storage, if there is no enough space on device. + +_Compute_ nodes are the endpoints, which are basically stateless postgres nodes, which communicates with pageservers and safekeepers to modify and read state of the database. By default, it is listening on `55433` port for postgres protocol. + +## Running storage engine + +## Running compute nodes \ No newline at end of file diff --git a/docs/media/neon-components.svg b/docs/media/neon-components.svg new file mode 100644 index 0000000000..f5de6f64a8 --- /dev/null +++ b/docs/media/neon-components.svg @@ -0,0 +1,4 @@ + + + +
Safekeeper 2
Safekeeper 2
if connected
if connected
Pageserver
Pageserver
:9898
:9898
:6400
:6400
S3-compatible
remote storage
S3-compatible...
:9000
:9000
http api
http api
pg protocol
pg protocol
Storage Broker
Storage Broker
:50051
:50051
grpc
grpc
optional
optional
Safekeeper 3
Safekeeper 3
Safekeeper 1
Safekeeper 1
read data
read data
write to WAL
to all safekeepers
write to WAL...
Compute
(postgres)
Compute...
:3080
:3080
:55433
:55433
http api
http api
pg protocol
pg protocol
:5454
:5454
:5454
:5454
:5454
:5454
if connected
if connected
psql/other clients
psql/other clients
:7676
:7676
http api
http api
:7676
:7676
http api
http api
:7676
:7676
http api
http apiText is not SVG - cannot display \ No newline at end of file