Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update the quick start doc to reflect the latest changes #5116

Merged
merged 1 commit into from
Mar 31, 2024
+62 −71
Merged

update the quick start doc to reflect the latest changes #5116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 31 additions & 37 deletions docs/en/deployment/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
In order to let you get started with Apollo Configuration Center faster, we have prepared a Quick Start here, which can deploy and start Apollo Configuration Center in your local environment in a few minutes.
To help you quickly get started with the Apollo Configuration Center, we have prepared a Quick Start here, which can deploy and start Apollo Configuration Center in your local environment in a few minutes.

If you are familiar with Docker, you can refer to [Apollo Quick Start Docker Deployment](en/deployment/quick-start-docker) to deploy Apollo via Docker. Apollo Quick Start Docker.

Expand Down Expand Up @@ -49,7 +49,7 @@ We have prepared a Quick Start installation package, you just need to download i
The installation package is 50M, if you can't access github, you can download it from Baidu.com.

1. Download from GitHub
* Checkout or download the [apollo-build-scripts project](https://github.com/apolloconfig/apollo-quick-start)
* Checkout or download the [apollo-quick-start project](https://github.com/apolloconfig/apollo-quick-start)
* **Since the Quick Start project is relatively large, it is placed in a different repository, so please note the project address**
* https://github.com/apolloconfig/apollo-quick-start
2. Download from Baidu.com
Expand All @@ -69,12 +69,12 @@ Quick Start is only for local testing, so generally users do not need to downloa
# II. Initialization and Startup
#### Precautions
1. The Apollo server process needs to use ports 8070, 8080, 8090 respectively, please ensure these three ports are not currently in use.
2. The `github` in the SPRING_PROFILES_ACTIVE environment variable in the script is a required profile, `auth` is a profile that provides simple authentication for the portal, it can be removed if authentication is not required or other authentication methods are used.
2. The `github` in the SPRING_PROFILES_ACTIVE environment variable in the script is a required profile, `database-discovery` specifies the use of database service discovery, `auth` is a profile that provides simple authentication for the portal, it can be removed if authentication is not required or other authentication methods are used.
## 2.1 Use H2 in-memory database, automatic initialization
No configuration is required, just use the following command to start
> Note: When using the in-memory database, any operation will be lost after the Apollo process restarts
```bash
export SPRING_PROFILES_ACTIVE="github,auth"
export SPRING_PROFILES_ACTIVE="github,database-discovery,auth"
unset SPRING_SQL_CONFIG_INIT_MODE
unset SPRING_SQL_PORTAL_INIT_MODE
java -jar apollo-all-in-one.jar
Expand All @@ -88,7 +88,7 @@ java -jar apollo-all-in-one.jar
### 2.2.1 First startup
Use the SPRING_SQL_CONFIG_INIT_MODE="always" and SPRING_SQL_PORTAL_INIT_MODE="always" environment variable for initialization at the first startup
```bash
export SPRING_PROFILES_ACTIVE="github,auth"
export SPRING_PROFILES_ACTIVE="github,database-discovery,auth"
# config db
export SPRING_SQL_CONFIG_INIT_MODE="always"
export SPRING_CONFIG_DATASOURCE_URL="jdbc:h2:file:~/apollo/apollo-config-db;mode=mysql;DB_CLOSE_ON_EXIT=FALSE;DB_CLOSE_DELAY=-1;BUILTIN_ALIAS_OVERRIDE=TRUE;DATABASE_TO_UPPER=FALSE"
Expand All @@ -102,7 +102,7 @@ java -jar apollo-all-in-one.jar
### 2.2.2 Subsequent startup
Remove the SPRING_SQL_CONFIG_INIT_MODE and SPRING_SQL_PORTAL_INIT_MODE environment variable to avoid repeated initialization at subsequent startup
```bash
export SPRING_PROFILES_ACTIVE="github,auth"
export SPRING_PROFILES_ACTIVE="github,database-discovery,auth"
# config db
unset SPRING_SQL_CONFIG_INIT_MODE
export SPRING_CONFIG_DATASOURCE_URL="jdbc:h2:file:~/apollo/apollo-config-db;mode=mysql;DB_CLOSE_ON_EXIT=FALSE;DB_CLOSE_DELAY=-1;BUILTIN_ALIAS_OVERRIDE=TRUE;DATABASE_TO_UPPER=FALSE"
Expand All @@ -121,7 +121,7 @@ java -jar apollo-all-in-one.jar
### 2.3.1 First startup
Use the SPRING_SQL_INIT_MODE="always" environment variable for initialization at the first startup
```bash
export SPRING_PROFILES_ACTIVE="github,auth"
export SPRING_PROFILES_ACTIVE="github,database-discovery,auth"
# config db
export SPRING_SQL_CONFIG_INIT_MODE="always"
export SPRING_CONFIG_DATASOURCE_URL="jdbc:mysql://your-mysql-server:3306/ApolloConfigDB?useUnicode=true&characterEncoding=UTF8"
Expand All @@ -139,7 +139,7 @@ java -jar apollo-all-in-one.jar
### 2.3.2 Subsequent startup
Remove the SPRING_SQL_CONFIG_INIT_MODE and SPRING_SQL_PORTAL_INIT_MODE environment variable to avoid repeated initialization at subsequent startup
```bash
export SPRING_PROFILES_ACTIVE="github,auth"
export SPRING_PROFILES_ACTIVE="github,database-discovery,auth"
# config db
unset SPRING_SQL_CONFIG_INIT_MODE
export SPRING_CONFIG_DATASOURCE_URL="jdbc:mysql://your-mysql-server:3306/ApolloConfigDB?useUnicode=true&characterEncoding=UTF8"
Expand All @@ -166,7 +166,7 @@ You can import [apolloportaldb.sql](https://github.com/apolloconfig/apollo/blob/
2. The "apollo-username" and "apollo-password" in the environment variables in the script need to fill in the actual username and password

```bash
export SPRING_PROFILES_ACTIVE="github,auth"
export SPRING_PROFILES_ACTIVE="github,database-discovery,auth"
# config db
unset SPRING_SQL_CONFIG_INIT_MODE
export SPRING_CONFIG_DATASOURCE_URL="jdbc:mysql://your-mysql-server:3306/ApolloConfigDB?useUnicode=true&characterEncoding=UTF8"
Expand All @@ -181,13 +181,7 @@ java -jar apollo-all-in-one.jar

```

# III. Additional Startup Instructions
## 3.1 Troubleshooting
If you encounter an exception in the startup, you can check the log files in the service and portal directories respectively to troubleshoot the problem.

> Note: During start-up, eureka registration failure message will be output in the log, e.g. `com.sun.jersey.api.client.ClientHandlerException: java.net.ConnectException: Connection refused`. Note that this is expected because apollo-configservice needs to register the service with Meta Server (itself), but since it is not up yet during the startup process itself, this error is reported. A retry action will be performed later, so it will register properly when the service is up by itself.

## 3.2 Note
# III. Note

Quick Start is only used to help you quickly experience Apollo project, please refer to: [distributed-deployment-guide](en/deployment/distributed-deployment-guide) for details.

Expand All @@ -196,21 +190,30 @@ It should be noted that Quick Start does not support adding environments, but on
# IV. Using Apollo Configuration Center
## 4.1 Using the sample project

### 4.1.1 Viewing the sample configuration
### 4.1.1 Initialize the sample configuration
1. Open http://localhost:8070

> Quick Start integrates with [Spring Security simple authentication](en/extension/portal-how-to-implement-user-login-function?id=implementation-1-simple-authentication-using-spring-security-provided-by-apollo), for more information you can refer to [Portal implementing user login function](en/extension/portal-how-to-implement-user-login-function)

<img src="https://github.com/apolloconfig/apollo-quick-start/raw/master/images/apollo-login.png" alt="login" width="640px">
<img src="https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/apollo-login-en.jpg" alt="login" width="640px">

2. Enter username apollo and password admin and log in

![Home](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-build-scripts@master/images/apollo-sample-home.png)
![Home](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/apollo-sample-home-en.jpg)

3. Click "Create project", enter the `SampleApp` information, and submit.

![Create project](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/apollo-create-sample-app-en.jpg)

4. Go to the SampleApp configuration interface, click on "Add Configuration", enter the `timeout` information, and submit.

3. Click on SampleApp to enter the configuration screen, you can see that there is currently a configuration timeout=100
![Configuration Console](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-build-scripts@master/images/sample-app-config.png)
![Add configuration](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/apollo-create-sample-config-en.jpg)

> If prompted `system error, please retry or contact system owner`, please retry a few seconds later, because there is a refresh delay for services registered through Eureka.
5. Click on the "Release" button, and fill in the release information.

![Configuration page](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/sample-app-config-en.jpg)

![Release page](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/sample-app-release-detail-en.jpg)

### 4.1.2 Running the client application
We have prepared a simple [Demo client](https://github.com/apolloconfig/apollo-demo-java/blob/main/api-demo/src/main/java/com/apolloconfig/apollo/demo/api/SimpleApolloConfigDemo.java) to demonstrate getting configuration from Apollo Configuration Center.
Expand All @@ -229,7 +232,7 @@ Apollo Config Demo. Please input key to get the value. Input quit to exit.
Enter ``timeout`` and you will see the following message.
```sh
> timeout
> [SimpleApolloConfigDemo] Loading key : timeout with value: 100
Loading key : timeout with value: 1000
```

> If you encounter problems running the client, you can view more detailed logging information by changing the level in ``client/log4j2.xml`` to DEBUG
Expand All @@ -241,30 +244,21 @@ Enter ``timeout`` and you will see the following message.

### 4.1.3 Modify the configuration and publish

1. In the configuration screen, click the edit button for the timeout item
![Edit Configuration](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-build-scripts@master/images/sample-app-modify-config.png)

2. In the popup box, change the value to 200 and submit
![Update Configuration](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-build-scripts@master/images/sample-app-submit-config.png)



3. Click the Publish button and fill in the publish information
![Publish Configuration](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-build-scripts@master/images/sample-app-release-config.png)
Return to the configuration interface, change the value of `timeout` to 2000, and release the configuration.

![Release Info](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-build-scripts@master/images/sample-app-release-detail.png)
![Modify configuration](https://cdn.jsdelivr.net/gh/apolloconfig/apollo-quick-start@master/images/sample-app-modify-config-en.jpg)

### 4.1.4 Client view the modified value
If the client has been running, it will listen for configuration changes after the configuration is published and output the modified configuration information as follows.
```sh
[SimpleApolloConfigDemo] Changes for namespace application
[SimpleApolloConfigDemo] Change - key: timeout, oldValue: 100, newValue: 200, changeType: MODIFIED
Changes for namespace application
Change - key: timeout, oldValue: 1000, newValue: 2000, changeType: MODIFIED
```

Type ``timeout`` again to see the corresponding value and you will see the following message.
```sh
> timeout
> [SimpleApolloConfigDemo] Loading key : timeout with value: 200
Loading key : timeout with value: 2000
```

## 4.2 Using the new project
Expand Down
Loading
Loading