Skip to content

Latest commit

 

History

History
161 lines (101 loc) · 5.96 KB

3.DEVELOPMENT_EN.md

File metadata and controls

161 lines (101 loc) · 5.96 KB
Raw

Development Document

1. How to Upload Image

(1) Upload a Basic Image

Assuming there is a service named etcd locally, with the image name sparrow-basic-etcd and version 3.5.0. If you want to upload this image to Docker Hub, you need to use the following commands

./sparrowtool upload -t basic -s etcd -v 3.5.0

It must be noted that after upload, the version of the remote image may not be the same as the local version.

  • local image version: 3.5.0
  • remote image version: 1.0.{{timestamp}}

image

In order to prevent the remote image version from being mistakenly replaced, if you want to upload a version same to the local one, you must use the -r option, it means replace, such as -r true.

./sparrowtool upload -t basic -s etcd -v 3.5.0 -r true

This way, there will be a remote image with version 3.5.0.

image

(2) Upload a App Image

The usage is the same as above, not repeated here.

./sparrowtool upload -t app -s etcd -v latest

./sparrowtool upload -t app -s etcd -v latest -r true

2. How to Create New Service

(1) Use Sparrowtool

You can use the sparrowtool to create new service. If you want to create a jupyter service, you can use this command bellow.

# if you forget command, for help.
./sparrowtool --help

./sparrowtool new -t service -s jupyter -p 2300 -v 0.1.0

After a successful execution, there will be a directory named /jupyter under the project root directory.

① Assign a Port Number

If you don't know which port number to use, you add your service(such as langchain) to subdirectories=("etcd" "etcdkeeper" ... "langchain") of search_env() in sparrowtool file. Then run this command bellow.

./sparrowtool env -l _port

From the image below, you can see that the system has allocated a port range of [3300, 3400) to the new service langchain.

image

(2) Modify Your Service Configuration

You must modify these image variables in ./jupyter/.env file as bellow.

  • IMAGE_OFFICIAL_JUPYTER_NAME: the official image name.
  • IMAGE_OFFICIAL_JUPYTER_VERSION: [optional modify] the official image version, such as IMAGE_OFFICIAL_JUPYTER_VERSION=18.19.0.
  • IMAGE_BASIC_JUPYTER_VERSION: [optional modify] the basic image version. It is recommended to set the same value as IMAGE_OFFICIAL_JUPYTER_VERSION.
  • IMAGE_APP_JUPYTER_VERSION: [optional modify] the app image name. It is recommended to set latest

These are must modify variables, if you have another demand, you can modify more in the ./jupyter directory.

(3) Add Your Service to ENABLE_SERVICE_LIST in Your /.work/config/.env File

The ENABLE_SERVICE_LIST variables is defined in /.work/config/.env.amd64 or /.work/config/.env.arm64 file, you should add jupyter the new service to the variable.

ENABLE_SERVICE_LIST=("xxx" "xxx" "jupyter")

(4) Delete /.env File

After that, you should delete /.env file in the root path of your project, because an updated /.env file can be automatically generated in a while.

(5) Start Service

Now, you can enjoy the service use the following command.

./sparrow startone jupyter

Of course, if you need to make some custom modifications to the image, you can update the service ! Please continue to the next part: How to update a service doc

3、How to Update a Service

When the content of the image needs to be modified to support new requirements, the services need to be updated, which is actually updating the image.

(1) Update a Service

./sparrow updateone {service}

(2) Usage Example

When we need to adjust the Go version to 1.17.0 (default is 1.21.1), follow these steps:

  1. First, modify the official image: change IMAGE_OFFICIAL_GO_VERSION=1.21.1 in the /.env file to IMAGE_OFFICIAL_GO_VERSION=1.17.0.
  2. Then, modify the basic image: change IMAGE_BASIC_GO_VERSION=1.21.1 in the /.env file to IMAGE_BASIC_GO_VERSION=1.17.0.
  3. Finally, update the go service: execute ./sparrow updateone go.

4、How Nginx Proxy Pass Server

image

(1) Container Config

GO_HOST_PORT=8002 # port number of the host that deployed the go service.
GO_CONTAINER_PORT=8001 # port number of go container

NGINX_HOST_GO_PROXY_PORT=8004 # the host port number for nginx proxying the go service.
NGINX_CONTAINER_GO_PROXY_PORT=8003 # the container port number for nginx proxying the go service.

(2) Proxy Config

server {
    listen {{go_proxy_port}};

    location / {
        proxy_pass http://{go_server_addr}:{{go_server_port}};
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    error_log /var/log/nginx/nginx_error.log;
    access_log /var/log/nginx/goproxy_access.log;
}

5、The Mounting of Service on The Host

(1) Service Directory Mounting

Each service directory will be mounted to the /home/sparrow/{service} directory of the container.

(2) Data Directory Mounting

Each service has a data directory, which is the only data channel from the host to the container. For example

  • the persistent data of databases like MySQL and Redis will be mounted to their data directories.
  • projects based on environments such as Python/PHP/Go will be mounted to their ata directories.