Protei/PromucFlow_constructor
2
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Update ServerSetup.md for clarity (#4940)

Browse Source 
The following changes have been done to improve this document:
* The main change done is to bring the sections `Setting up a local MongoDB instance` and `Setting up a local Redis instance` under the prerequisites section. This improves the structure of the document as the reader can linearly go through it and set up the dependencies before setting up the Appsmith server.
* Apart from this, each section flows much more naturally to the next section as the last sentence of each section sets up the context about what's next.
* Other minor language improvements.
This commit is contained in:
Raminder Singh 2021-06-14 00:37:53 +05:30 committed by GitHub
parent 9d6247672a
commit 81954182c1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 52 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
contributions/ServerSetup.md
View File

@ -1,30 +1,60 @@
## Running Server Codebase
The server codebase is written in Java and is powered by Spring + WebFlux. This document explains how you can setup a development environment to make changes and test your changes.
This document explains how you can setup a development environment for Appsmith server. As the server codebase is written in Java and is powered by Spring + WebFlux we need Java and Maven installed to build the code. In addition we also need one instance of MongoDB and Redis each to run Appsmith server. Lastly, we will set up IntelliJ IDEA to let you edit the code. Let's get those prerequisites installed on your machine.
>For details on setting up with `Docker`, please refer to the [Setup Guide](../app/server/README.md#run-locally-with-docker)
>If you are not setting up a development environment you can get the Appsmith server up and running quickly with `Docker`. Please refer to the [Setup Guide](../app/server/README.md#run-locally-with-docker) on how to do that.
## Pre-requisites
- Java --- OpenJDK 11.
- Maven --- version 3+ (preferably 3.6).
- A MongoDB database --- A simple way to get this up is explained [further down in this document](#setting-up-a-local-mongodb).
- A Redis instance --- A simple way to get this up is explained [further down in this document](#setting-up-a-local-redis).
- An IDE --- We use IntelliJ IDEA as our primary IDE for backend development.
Before you can start to hack on the Appsmith server, your machine should have the following installed:
## Steps for Setup
- Java - OpenJDK 11.
- Maven - Version 3+ (preferably 3.6).
- A MongoDB database - Refer to the [Setting up a local MongoDB instance](#setting-up-a-local-mongodb-instance) section to setup a MongoDB instance using `Docker`.
- A Redis instance - Refer to the [Setting up a local Redis instance](#setting-up-a-local-redis-instance) section to setup a Redis instance using `Docker`.
- An IDE - We use IntelliJ IDEA as our primary IDE for backend development. To set it up, refer to the [Setting up IntelliJ IDEA](#setting-up-intellij-idea) section.
1. After cloning the repository, change your directory to `app/server`
This document doesn't provide instructions to install Java and Maven because these vary between different operating systems and distributions. Please refer to the documentation of your operating system or package manager to install these. Next we will setup MondoDB and Redis using `Docker`.
2. Run the command
### Setting up a local MongoDB instance
The following command will start a MongoDB docker instance locally:
```sh
docker run -p 127.0.0.1:27017:27017 --name appsmith-mongodb -e MONGO_INITDB_DATABASE=appsmith -v /path/to/store/data:/data/db mongo
```
Please change the `/path/to/store/data` to a valid path on your system. This is where MongoDB will persist it's data across runs of this container.
Note that this command doesn't set any username or password on the database so we make it accessible only from localhost using the `127.0.0.1:` part in the port mapping argument. Please refer to the documentation of this image to learn [how to set a username and password](https://hub.docker.com/_/mongo).
MongoDB will now be running on `mongodb://localhost:27017/appsmith`.
### Setting up a local Redis instance
The following command will start a Redis docker instance locally:
```sh
docker run -p 127.0.0.1:6379:6379 --name appsmith-redis redis
```
Redis will now be running on `redis://localhost:6379`.
With the prerequisites met, let's build the code.
## Building and running the code
1. Clone Appsmith repository.
2. Change your directory to `app/server`.
3. Run the following command:
```sh
mvn clean compile
```
This generates a bunch of classes required by IntelliJ for compiling the rest of the source code. Without this step, your IDE may complain about missing classes and will be unable to compile the code.
3. Create a copy of the `envs/dev.env.example`
4. Create a copy of the `envs/dev.env.example`
```sh
cp envs/dev.env.example .env
@ -32,14 +62,14 @@ cp envs/dev.env.example .env
This command creates a `.env` file in the `app/server` folder. All run scripts pick up environment configuration from this file.
4. Modify the property values in the file `.env` to point to your local running instance of MongoDB and Redis.
5. Ensure that the environment variables `APPSMITH_MONGODB_URI` and `APPSMITH_REDIS_URI` in the file `.env` point to your local running instances of MongoDB and Redis.
5. In order to create the final JAR for the Appsmith server, run the command:
6. Run the following command to create the final JAR for the Appsmith server:
```
./build.sh
```
This command will create a `dist` folder which contains the final packaged jar along with multiple jars for the binaries for plugins as well.
This command will create a `dist` folder which contains the final packaged jar along with multiple jars for plugins as well.
Note:
- If you want to skip tests, you can pass `-DskipTests` flag to the build cmd.
@ -55,7 +85,7 @@ Check failed: Docker environment should have more than 2GB free disk space.
There are two ways to resolve this issue: (1) free up more space (2) change docker's data root path.
6. Start the Java server by running
7. Start the Java server by running
```
./scripts/start-dev-server.sh
@ -63,35 +93,13 @@ There are two ways to resolve this issue: (1) free up more space (2) change dock
By default, the server will start on port 8080.
7. When the server starts, it automatically runs migrations on MongoDB and will populate it with some initial required data.
8. When the server starts, it automatically runs migrations on MongoDB and will populate it with some initial required data.
8. You can check the status of the server by hitting the endpoint: [http://localhost:8080](http://localhost:8080) on your browser. By default you should see an HTTP 401 error.
9. You can check the status of the server by hitting the endpoint: [http://localhost:8080](http://localhost:8080) on your browser. By default you should see an HTTP 401 error.
## Setting up a local MongoDB
Now the last bit, let's get your Intellij IDEA up and running.
The following command can bring up a MongoDB docker instance locally.
```sh
docker run -p 127.0.0.1:27017:27017 --name appsmith-mongodb -e MONGO_INITDB_DATABASE=appsmith -v /path/to/store/data:/data/db mongo
```
Please change the `/path/to/store/data` to a valid path on your system. This is where MongoDB will persist it's data across runs of this container.
Note that this command doesn't set any username or password on the database so we make it accessible only from localhost using the `127.0.0.1:` part in the port mapping argument. Please refer to the documentation of this image to learn [how to set a username and password](https://hub.docker.com/_/mongo).
When using this command, the value of `APPSMITH_MONGODB_URI` should be set to `mongodb://localhost:27017/appsmith` (which is what's provided in the example env file).
## Setting up a local Redis
The following command can bring up a Redis docker instance locally.
```sh
docker run -p 127.0.0.1:6379:6379 --name appsmith-redis redis
```
When using this command, the value of `APPSMITH_REDIS_URI` should be set to `redis://localhost:6379`.
## Seting up IntelliJ IDE
## Setting up IntelliJ IDEA
To run the project from within the IDE, you will need to make use of the run configuration that is part of the repository. The run configuration uses the [EnvFile](https://plugins.jetbrains.com/plugin/7861-envfile) plugin to include environment variables in the path. Any and all tests can be run within the IDE by cloning this run configuration.
@ -109,7 +117,8 @@ Please note when setting **Working directory** option. If the path is not correc
3. Load your env file by going to the EnvFile Tab in the Run/Debug configuration settings for your server.
<img width="1067" alt="Screenshot 2021-03-03 at 1 49 17 PM" src="https://user-images.githubusercontent.com/458946/109775238-451c8d80-7c27-11eb-98ad-61fc33082b63.png">
Happy hacking.
## Need Assistance
## Need Assistance?
- If you are unable to resolve any issue while doing the setup, please feel free to ask questions on our [Discord channel](https://discord.com/invite/rBTTVJp) or initiate a [Github discussion](https://github.com/appsmithorg/appsmith/discussions) or send an email to `support@appsmith.com`. We'll be happy to help you.
- In case you notice any discrepancy, please raise an issue on Github and/or send an email to support@appsmith.com.