diff --git a/contributions/ClientSetup.md b/contributions/ClientSetup.md index 416b8aa56849..d2dd4b1e82c1 100644 --- a/contributions/ClientSetup.md +++ b/contributions/ClientSetup.md @@ -9,92 +9,67 @@ Appsmith's client (UI/frontend) uses the ReactJS library and Typescript. The app On your development machine, please ensure that: 1. You have `docker` installed in your system. If not, please visit: [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/) -1. You have `mkcert` installed. Please visit: [https://github.com/FiloSottile/mkcert#installation](https://github.com/FiloSottile/mkcert#installation) for details. - - - For `mkcert` to work with Firefox, you may need to install the `nss` utility. Details are in the link above. - - On Linux, you can easily install `mkcert` using the following command - - ``` - curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest \ - | grep "browser_download_url.*linux-amd64" \ - | cut -d : -f 2,3 | tr -d \" \ - | wget -i - -O mkcert - chmod +x mkcert - sudo mv mkcert /usr/local/bin - ``` - -1. You have `envsubst` installed. Use `brew install gettext` on MacOS. Linux machines usually have this installed. -1. You have cloned the repo in your local machine. -1. You have yarn installed as a global npm package, i.e. `npm install -g yarn`. -1. Create local HTTPS certificates - - 1. Run the following command from the project root. - - ```bash - cd app/client/docker && mkcert -install && mkcert "*.appsmith.com" && cd ../../.. +2. You have `mkcert` installed. Please visit: [https://github.com/FiloSottile/mkcert#installation](https://github.com/FiloSottile/mkcert#installation) for details. + - For `mkcert` to work with Firefox, you may need to install the `nss` utility. Details are in the link above. + - On Linux, you can easily install `mkcert` using the following command + ``` + curl -s https://api.github.com/repos/FiloSottile/mkcert/releases/latest \ + | grep "browser_download_url.*linux-amd64" \ + | cut -d : -f 2,3 | tr -d \" \ + | wget -i - -O mkcert + chmod +x mkcert + sudo mv mkcert /usr/local/bin + ``` +3. You have `envsubst` installed. Use `brew install gettext` on MacOS. Linux machines usually have this installed. +4. You have cloned the repo in your local machine. +5. You have yarn installed as a global npm package, i.e. `npm install -g yarn`. +6. **Create local HTTPS certificates** + 1. Run from repo root: + ```bash + cd app/client/docker && mkcert -install && mkcert "*.appsmith.com" && cd ../../.. + ``` + This command will create 2 files in the `docker/` directory: + - `_wildcard.appsmith.com-key.pem` + - `_wildcard.appsmith.com.pem` + 2. Add the domain `dev.appsmith.com` to `/etc/hosts`. + ```bash + echo "127.0.0.1 dev.appsmith.com" | sudo tee -a /etc/hosts + ``` + Note: + - Please be careful when copying the above string as space between the IP and the string goes missing sometimes. + - Please check that the string is copied properly ``` - - This command will create 2 files in the `docker/` directory: - - - `_wildcard.appsmith.com-key.pem` - - `_wildcard.appsmith.com.pem` - - 1. Add the domain `dev.appsmith.com` to `/etc/hosts`. - - ```bash - echo "127.0.0.1 dev.appsmith.com" | sudo tee -a /etc/hosts + cat /etc/hosts | grep appsmith ``` - - Note: - - - Please be careful when copying the above string as space between the IP and the string goes missing sometimes. - - Please check that the string is copied properly - - ``` - cat /etc/hosts | grep appsmith - ``` - -1. Run cmd: `cp .env.example .env` -1. Run Backend server - - - The backend server can be run in two ways - 1. Use Appsmith's staging server hosted at `https://release.app.appsmith.com` for development purposes. (Recommended) - 1. Run the backend server locally. To setup the backend server locally, refer [here](#running-backend-locally). - - Run the script `start-https.sh` to start the nginx container that will proxy the frontend requests to the backend server. - - - Pass the server name as an argument to this command to use that server as backend. - - ```bash - cd app/client - ./start-https.sh https://release.app.appsmith.com // uses Appsmith's staging backend server as backend for your local frontend code - ``` - - - If you want to use the backend server running on your local, you do not need to pass a parameter when running `start-https.sh`. +7. Run from repo root: `cp .env.example .env` +8. Run Backend server + - The backend server can be run in two ways + 1. Use Appsmith's staging server hosted at `https://release.app.appsmith.com` for development purposes. **(Recommended)** + 2. Run the backend server locally. To setup the backend server locally, refer [here](#running-backend-locally). + - Run the script `start-https.sh` to start the nginx container that will proxy the frontend requests to the backend server. + - Pass the server name as an argument to this command to use that server as backend (run from repo root): + ```bash + cd app/client + ./start-https.sh https://release.app.appsmith.com // uses Appsmith's staging backend server as backend for your local frontend code + ``` + If you want to use the backend server running on your local, you do not need to pass a parameter when running `start-https.sh`. ### Steps to build & run the code: -1. Run `yarn install`. - - Note: - - - On the Ubuntu Linux platform, please run the following cmd before step 2 below: - - ``` - echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p - ``` - -1. Run `yarn start`. - - - 🎉 Your Appsmith client is now running on https://dev.appsmith.com. - - This URL must be opened with https and not have port 3000 in it. - -1. If yarn start throws mismatch node version error - - - This error occurs because the node version is not compatible with the app environment. In this case, Node version manager can be used, allowing multiple node versions in different projects. - - Check below for installation and usage details: - - 1. Install a node version manager. For eg: check [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). - 1. In the project's root, run `nvm use 20.11.1` or `fnm use 20.11.1`. +1. Run from `app/client`: `yarn install`. + Note: + - On the Ubuntu Linux platform, please run the following cmd before step 2 below: + ``` + echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p + ``` +2. Run from `app/client`: `yarn start`. + - 🎉 Your Appsmith client is now running on [https://dev.appsmith.com](https://dev.appsmith.com). + - **This URL must be opened with https and not have port 3000 in it.** +3. If yarn start throws mismatch node version error + - This error occurs because the node version is not compatible with the app environment. In this case, Node version manager can be used, allowing multiple node versions in different projects. + - Check below for installation and usage details: + 1. Install a node version manager. For eg: check [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). + 2. Run from `app/client`: `nvm use 20.11.1` or `fnm use 20.11.1`. ### Running Tests on Client @@ -107,7 +82,7 @@ On your development machine, please ensure that: ##### Setup Cypress configurations -To setup the configurations for running integration tests via Cypress, use these commands below, +To setup the configurations for running integration tests via Cypress, use these commands below (run from repo root): ```bash cd app/client/cypress/scripts @@ -119,27 +94,29 @@ To setup the configurations for running integration tests via Cypress, use these `Do you wish to continue without setting up the local server with docker? (yes/no):` **Options:** -- **`no`:** Selecting "no" will trigger the setup of a local server using Docker with the `appsmith-ce:release` image. -- **`yes`:** Selecting "yes" will skip the local server setup process. +- **no:** Selecting "no" will trigger the setup of a local server using Docker with the `appsmith-ce:release` image. +- **yes:** Selecting "yes" will skip the local server setup process. **Prompt:** `https://dev.appsmith.com is not accessible. Do you wish to continue without setting it up? (yes/no):` **Options:** -- **`no`:** Simply close the process. -- **`yes`:** Continue on the process for next stage + +- **no:** Simply close the process. +- **yes:** Continue on the process for next stage **Prompt:** `TED (TestEventDriver) is not running. Do you want to pull & run the latest Docker container for TED (TestEventDriver)? (yes/no):` **Options:** -- **`no`:** It will not create TED setup in local machine. -- **`yes`:** Download the TED image and run the image for test purposes. + +- **no:** It will not create TED setup in local machine. +- **yes:** Download the TED image and run the image for test purposes. ##### Running Cypress tests locally -To run a specific test file in headless fashion, use the following command: +To run a specific test file in headless fashion, use the following command (run from repo root): ```bash cd app/client/ @@ -147,7 +124,7 @@ To run a specific test file in headless fashion, use the following command: npx cypress run --spec --browser chrome ``` -To open Cypress in the browser and run the tests visually +To open Cypress in the browser and run the tests visually (run from repo root): ```bash cd app/client/ @@ -161,7 +138,7 @@ To open Cypress in the browser and run the tests visually 1. Running the server from source code. - Refer to [documentation](https://github.com/appsmithorg/appsmith/blob/release/contributions/ServerSetup.md) for setting up backend to do this. - 1. Running the server from a docker image. There are two ways to get a backend docker image + 2. Running the server from a docker image. There are two ways to get a backend docker image 1. Pull latest release branch docker image from Appsmith's public docker hub account. @@ -183,7 +160,7 @@ To open Cypress in the browser and run the tests visually ``` - 1. Create docker image from local source code + 2. Create docker image from local source code ``` cd ~/appsmith @@ -201,15 +178,12 @@ To open Cypress in the browser and run the tests visually ### Running Unit Tests -- To run the Jest unit tests, run: - +- To run the Jest unit tests, run from repo root: ```bash cd app/client yarn run test:unit ``` - -- To run a single jest test, - +- To run a single jest test, run from repo root: ```bash cd app/client @@ -220,8 +194,7 @@ To open Cypress in the browser and run the tests visually yarn jest src/widgets//.test.ts --silent=false ``` - -- To run a single jest test in watch mode, +- To run a single jest test in watch mode, run from `app/client`: ```bash npx jest --watch ``` @@ -257,7 +230,6 @@ After this, you can continue Setting up from [here](#pre-requisites). #### I am on WSL and can't reach dev.appsmith.com - You will need to add `dev.appsmith.com` to Windows' `C:\Windows\System32\drivers\etc\hosts` instead of `/etc/hosts`. Alternately, you can install a desktop environment in WSL to open `dev.appsmith.com` from a browser in WSL. - ``` 127.0.0.1 dev.appsmith.com ``` @@ -268,18 +240,17 @@ After this, you can continue Setting up from [here](#pre-requisites). - You can check logs with `docker logs wildcard-nginx`. - If you see `Address already in use` errors, look for the service running on port 80 and 443 with `lsof -i tcp:80,443 | grep LISTEN` and stop the process. - **Example**: Some Linux distros have `apache2` listening on 80. Stop them with `sudo systemctl stop apache2` #### I want to add dev.appsmith.com conf to my local Nginx without Docker. 1. Copy `app/client/docker/templates/nginx-app.conf.template` over to your nginx sites directory. -1. You can remove or replace values for all the `sub_filter`. None of those properties are required. -1. Change `proxy_pass` value for client from `__APPSMITH_CLIENT_PROXY_PASS__` to `http://localhost:3000` -1. Replace all occurrences of `__APPSMITH_SERVER_PROXY_PASS__` with `http://localhost:8080` (or the server you want to point to) -1. Generate the certificates manually via `mkcert`. -1. Change the value of the certificate location for keys `ssl_certificate` & `ssl_certificate_key` to the place where these certificates were generated. -1. Reload nginx! :tada: +2. You can remove or replace values for all the `sub_filter`. None of those properties are required. +3. Change `proxy_pass` value for client from `__APPSMITH_CLIENT_PROXY_PASS__` to `http://localhost:3000` +4. Replace all occurrences of `__APPSMITH_SERVER_PROXY_PASS__` with `http://localhost:8080` (or the server you want to point to) +5. Generate the certificates manually via `mkcert`. +6. Change the value of the certificate location for keys `ssl_certificate` & `ssl_certificate_key` to the place where these certificates were generated. +7. Reload nginx! :tada: ## I still need help! diff --git a/contributions/ServerSetup.md b/contributions/ServerSetup.md index 746f6d34528e..7f34256bf745 100644 --- a/contributions/ServerSetup.md +++ b/contributions/ServerSetup.md @@ -17,17 +17,20 @@ There are two ways to run Appsmith server. Running the Appsmith Docker image as a container will grant you a running Appsmith server, along with its dependencies, like MongoDB and Redis. This is the easiest way to get started with Appsmith server. 1. Clone the Appsmith repository and change into it + ``` git clone https://github.com/appsmithorg/appsmith.git cd appsmith ``` 2. Change your directory to `deploy/docker` + ```console cd deploy/docker ``` 3. Start + ```console docker-compose up -d ``` @@ -83,10 +86,12 @@ After updating `JAVA_HOME`, confirm `echo $JAVA_HOME` points to the Java 17 dire Please follow the below steps for enabling the replica set with mongo running inside the docker 1. Connect to the mongo db running with a mongo shell. Use the below command + ``` mongosh ``` 2. Once you are inside the mongo shell run the below command. + ``` rs.initiate({"_id": "rs0", "members" : [{"_id":0 , "host": "localhost:27017" }]}) ``` @@ -99,6 +104,7 @@ After updating `JAVA_HOME`, confirm `echo $JAVA_HOME` points to the Java 17 dire mongod --port 27017 --dbpath --replSet && mongo --eval “rs.initiate()” ``` - One can use following commands to check replica set status: + ``` mongo appsmith rs.status() @@ -131,7 +137,7 @@ With the prerequisites met, let's build the code. 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. 4. Setup Environment file - - Create a copy of the `envs/dev.env.example` + - Create a copy of the `envs/dev.env.example` (run from `app/server`): ```console cp envs/dev.env.example .env @@ -142,11 +148,12 @@ With the prerequisites met, let's build the code. 5. Ensure that the environment variables `APPSMITH_DB_URL` and `APPSMITH_REDIS_URI` in the file `.env` point to your local running instances of MongoDB and Redis. 6. **Update the replica set name with correct value in the mongo connection string in the [.env](#setup-environment-file) file.** The replica name is the same as passed [here](#setting-up-a-local-mongodb-instance) + ```bash APPSMITH_DB_URL="mongodb://localhost:27017/appsmith?replicaSet=" ``` -7. Run the following command to create the final JAR for the Appsmith server: +7. Run the following command from `app/server` to create the final JAR for the Appsmith server: ```console ./build.sh -Dmaven.test.skip @@ -166,6 +173,7 @@ With the prerequisites met, let's build the code. - #### Linux/Ubuntu Environments - On Ubuntu Linux environment docker needs root privilege, hence `./build.sh` script needs to be run with root privilege as well. - On Ubuntu Linux environment, the script may not be able to read `.env` file, so it is advised that you run the cmd like: + ```console sudo APPSMITH_DB_URL="mongodb://localhost:27017/appsmith" APPSMITH_REDIS_URL="redis://127.0.0.1:6379" APPSMITH_MAIL_ENABLED=false APPSMITH_ENCRYPTION_PASSWORD=abcd APPSMITH_ENCRYPTION_SALT=abcd ./build.sh ``` @@ -183,6 +191,7 @@ APPSMITH_GIT_ROOT=/absolute/path/to/git-storage **Steps to run RTS:** 1. Ensure you have Node.js 20.11.1 installed. If you have a different version, use a node version manager: + ```console nvm use 20.11.1 ``` @@ -191,24 +200,28 @@ APPSMITH_GIT_ROOT=/absolute/path/to/git-storage fnm use 20.11.1 ``` - 2. Navigate to the RTS directory: + 2. Navigate to the RTS directory (from repo root): + ```console cd app/client/packages/rts ``` 3. Create the environment file: + ```console cp .env.example .env ``` 4. Start the RTS server: + ```console ./start-server.sh ``` Keep this terminal running; RTS must stay up while the Java server is running. -10. Start the Java server by running +10. Start the Java server by running from repo root: + ```console ./app/server/scripts/start-dev-server.sh ``` @@ -304,7 +317,7 @@ 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. -4. Create a copy of the `envs/dev.env.example` +4. Create a copy of the `envs/dev.env.example` (run from `app/server`): ```console cp envs/dev.env.example .env @@ -314,7 +327,7 @@ This command creates a `.env` file in the `app/server` folder. All run scripts p 5. Ensure that the environment variables `APPSMITH_DB_URL` and `APPSMITH_REDIS_URI` in the file `.env` point to your local running instances of MongoDB and Redis. -6. Run the following command to create the final JAR for the Appsmith server: +6. Run the following command from `app/server` to create the final JAR for the Appsmith server: ```console ./build.sh -DskipTests @@ -324,7 +337,8 @@ This command will create a `dist` folder which contains the final packaged jar a Note: - If you want to run the tests, you can remove `-DskipTests` flag from the build cmd. - On Ubuntu Linux environment docker needs root privilege, hence ./build.sh script needs to be run with root privilege as well. -- On Ubuntu Linux environment, the script may not be able to read .env file, so it is advised that you run the cmd like: +- On Ubuntu Linux environment, the script may not be able to read .env file, so it is advised that you run the cmd from `app/server` like: + ```console sudo APPSMITH_DB_URL="mongodb://localhost:27017/appsmith" APPSMITH_REDIS_URL="redis://127.0.0.1:6379" APPSMITH_MAIL_ENABLED=false APPSMITH_ENCRYPTION_PASSWORD=abcd APPSMITH_ENCRYPTION_SALT=abcd ./build.sh ``` @@ -342,6 +356,7 @@ There are two ways to resolve this issue: (1) free up more space (2) change dock **Steps to run RTS:** 1. Ensure you have Node.js 20.11.1 installed. If you have a different version, use a node version manager: + ```console nvm use 20.11.1 ``` @@ -350,24 +365,27 @@ There are two ways to resolve this issue: (1) free up more space (2) change dock fnm use 20.11.1 ``` - 2. Navigate to the RTS directory: + 2. Navigate to the RTS directory (from repo root): + ```console cd app/client/packages/rts ``` 3. Create the environment file: + ```console cp .env.example .env ``` 4. Start the RTS server: + ```console ./start-server.sh ``` Keep this terminal running; RTS must stay up while the Java server is running. -8. Start the Java server by running +8. Start the Java server by running from `app/server`: ```console ./scripts/start-dev-server.sh @@ -412,7 +430,7 @@ After configuring settings as mentioned above, please also add the following to Happy hacking ✌️ #### Note: -In case the server doesn't work with the above config, please try re-compiling the code using the steps +In case the server doesn't work with the above config, please try re-compiling the code from `app/server` using the steps: ```console mvn -B clean compile && ./build.sh -DskipTests @@ -421,7 +439,8 @@ mvn -B clean compile && ./build.sh -DskipTests 1. Ensure that you have Redis running on your local system. -2. Run the command to execute tests +2. Run the command to execute tests from repo root: + ```console cd app/server mvn clean package