chore: Fix client setup documentation: Add steps for running backend server from docker + run jest tests locally + fix overall structure (#23898)
Fix documentation for client setup
This commit is contained in:
Rajat Agrawal
GitHub
parent
13ac6db8d9
commit
c9004b6410
|
|
@ -9,66 +9,63 @@ 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.
|
||||
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
|
||||
|
||||
Note:
|
||||
|
||||
- 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
|
||||
```
|
||||
```
|
||||
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. <b>Create local HTTPS certificates</b>
|
||||
|
||||
### Create local HTTPS certificates:
|
||||
1. Run the following command from the project root.
|
||||
```bash
|
||||
cd app/client/docker && mkcert -install && mkcert "*.appsmith.com" && cd ../../..
|
||||
```
|
||||
|
||||
1. Run the following command from the project root.
|
||||
This command will create 2 files in the `docker/` directory:
|
||||
|
||||
```bash
|
||||
cd app/client/docker && mkcert -install && mkcert "*.appsmith.com" && cd ../../..
|
||||
```
|
||||
- `_wildcard.appsmith.com-key.pem`
|
||||
- `_wildcard.appsmith.com.pem`
|
||||
|
||||
This command will create 2 files in the `docker/` directory:
|
||||
1. Add the domain `dev.appsmith.com` to `/etc/hosts`.
|
||||
|
||||
- `_wildcard.appsmith.com-key.pem`
|
||||
- `_wildcard.appsmith.com.pem`
|
||||
```bash
|
||||
echo "127.0.0.1 dev.appsmith.com" | sudo tee -a /etc/hosts
|
||||
```
|
||||
|
||||
1. Add the domain `dev.appsmith.com` to `/etc/hosts`.
|
||||
Note:
|
||||
|
||||
```bash
|
||||
echo "127.0.0.1 dev.appsmith.com" | sudo tee -a /etc/hosts
|
||||
```
|
||||
- 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
|
||||
|
||||
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
|
||||
```
|
||||
```
|
||||
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. <b>(Recommended)</b>
|
||||
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.
|
||||
|
||||
1. Run the script `start-https.sh` to start the Nginx container that will proxy the frontend code on your local system.
|
||||
```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
|
||||
```
|
||||
|
||||
```bash
|
||||
cd app/client
|
||||
./start-https.sh
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- 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`.
|
||||
- If you want to use release.app.appsmith as your backend server, please check out the section - [If you would like to hit a different Appsmith server](#if-you-would-like-to-hit-a-different-appsmith-server)
|
||||
- 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:
|
||||
|
||||
|
|
@ -82,84 +79,112 @@ sudo mv mkcert /usr/local/bin
|
|||
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
|
||||
```
|
||||
|
||||
2. Run `yarn start`.
|
||||
1. Run `yarn start`.
|
||||
|
||||
🎉 Your Appsmith client is now running on https://dev.appsmith.com.
|
||||
- 🎉 Your Appsmith client is now running on https://dev.appsmith.com.
|
||||
- <b>This URL must be opened with https and not have port 3000 in it.</b>
|
||||
|
||||
This URL must be opened with https and not have port 3000 in it.
|
||||
1. If yarn start throws mismatch node version error
|
||||
|
||||
#### Note:
|
||||
- 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:
|
||||
|
||||
- By default, your client app points to the local API server - `http://host.docker.internal:8080` for MacOS or `http://localhost:8080` for Linux. If you don't have the API server running on your local system, your page will load with errors. To set up the API server on your local system, please follow the instructions [here](https://github.com/appsmithorg/appsmith/blob/release/contributions/ServerSetup.md)
|
||||
- If you cannot set up the API server on your local system, you can also [use Appsmith's staging API server](#if-you-would-like-to-hit-a-different-appsmith-server).
|
||||
|
||||
#### 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 16.14.0` or `fnm use 16.14.0`.
|
||||
|
||||
#### If you would like to hit a different Appsmith server:
|
||||
|
||||
- You can pass the server URL as an arg to the `start-https.sh` script.
|
||||
|
||||
```bash
|
||||
./start-https.sh https://release.app.appsmith.com
|
||||
```
|
||||
|
||||
- Run
|
||||
|
||||
```
|
||||
yarn
|
||||
yarn start
|
||||
```
|
||||
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 16.14.0` or `fnm use 16.14.0`.
|
||||
|
||||
### Running Tests on Client
|
||||
|
||||
1. To run the Cypress integration tests, you can create a local file `app/client/cypress.env.json` to populate `USERNAME` and `PASSWORD` env variables or use one of the methods [from their docs](https://docs.cypress.io/guides/guides/environment-variables.html#Setting).
|
||||
#### Integration Tests
|
||||
- To pass credentials for logging in your cypress tests, you can create a local file `app/client/cypress.env.json` to populate `USERNAME` and `PASSWORD` env variables or use one of the methods [from their docs](https://docs.cypress.io/guides/guides/environment-variables.html#Setting).
|
||||
|
||||
```json
|
||||
{
|
||||
"USERNAME": "Enter username",
|
||||
"PASSWORD": "Enter password"
|
||||
}
|
||||
```
|
||||
2. In order to run cypress tests which use datasources/rest api, you will need to have TED container running: (It bundles multiple services together along with fake data for testing)
|
||||
```
|
||||
docker pull appsmith/test-event-driver
|
||||
```
|
||||
```
|
||||
docker run --name appsmithted -d -p 2222:22 -p 5001:5001 -p 3306:3306 -p 28017:27017 -p 5432:5432 -p 25:25 -p 5000:5000 -p 3000:3000 -v `pwd`/git-server/keys:/git-server/keys -v `pwd`/git-server/repos:/git-server/repo appsmith/test-event-driver
|
||||
```
|
||||
Note : You need to have client and server running locally to run TED
|
||||
```json
|
||||
{
|
||||
"USERNAME": "Enter username",
|
||||
"PASSWORD": "Enter password"
|
||||
}
|
||||
```
|
||||
- To run cypress application for running tests, use these commands below,
|
||||
```bash
|
||||
cd app/client
|
||||
yarn run cytest
|
||||
```
|
||||
|
||||
1. run:
|
||||
- In order to run cypress tests which use datasources/rest api, you will need to have TED (Test Event Driver) container running: (It bundles multiple services together along with fake data for testing)
|
||||
```
|
||||
docker pull appsmith/test-event-driver
|
||||
|
||||
docker run --name appsmithted -d -p 2222:22 -p 5001:5001 -p 3306:3306 -p 28017:27017 -p 5432:5432 -p 25:25 -p 5000:5000 -p 3000:3000 -v `pwd`/git-server/keys:/git-server/keys -v `pwd`/git-server/repos:/git-server/repo appsmith/test-event-driver
|
||||
```
|
||||
|
||||
```bash
|
||||
cd app/client
|
||||
yarn run test
|
||||
```
|
||||
- You need to have client and server running locally to run TED
|
||||
|
||||
Please check out our [Testing Contribution](docs/TestAutomation.md) guide for more details on setting up & troubleshooting Cypress runs on your machine.
|
||||
- <b><a name="running-backend-locally">Running appsmith backend server locally</a></b>
|
||||
- There are two configurations available for running the backend server locally.
|
||||
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
|
||||
1. Pull latest release branch docker image from Appsmith's public docker hub account.
|
||||
|
||||
4. To run the Jest unit tests, run:
|
||||
```
|
||||
docker rm appsmith;
|
||||
|
||||
```bash
|
||||
cd app/client
|
||||
yarn run test:unit
|
||||
```
|
||||
cd ~/appsmith;
|
||||
|
||||
To run a single jest test,
|
||||
```bash
|
||||
cd app/client
|
||||
npx jest <file_path/file_name>
|
||||
```
|
||||
rm -rf stacks;
|
||||
|
||||
To run a single jest test in watch mode,
|
||||
```bash
|
||||
npx jest --watch <file_path/file_name>
|
||||
```
|
||||
docker pull appsmith/appsmith-ce
|
||||
|
||||
docker run -d --name appsmith -p 8000:80 -p 9001:9001 appsmith/appsmith-ce:latest;
|
||||
|
||||
docker logs -f appsmith;
|
||||
|
||||
./start-https.sh http://localhost:8000 // if nginx is installed locally
|
||||
./start-https.sh http://host.docker.internal:8000 // if nginx is running on docker
|
||||
|
||||
```
|
||||
|
||||
|
||||
1. Create docker image from local source code
|
||||
|
||||
```
|
||||
cd ~/appsmith
|
||||
./scripts/local_testing.sh -l # This builds a fat docker image of local backend and frontend
|
||||
# The docker image created above will show up in your docker desktop application
|
||||
|
||||
docker run -d --name appsmith -p 8000:80 -p 9001:9001 appsmith/appsmith-ce:local-testing;
|
||||
|
||||
./start-https.sh http://localhost:8000 // if nginx is installed locally
|
||||
./start-https.sh http://host.docker.internal:8000 // if nginx is running on docker
|
||||
|
||||
```
|
||||
- Please check out our [Testing Contribution](docs/TestAutomation.md) guide for more details on setting up & troubleshooting Cypress runs on your machine.
|
||||
|
||||
|
||||
### Running Unit Tests
|
||||
|
||||
- To run the Jest unit tests, run:
|
||||
|
||||
```bash
|
||||
cd app/client
|
||||
yarn run test:unit
|
||||
```
|
||||
|
||||
- To run a single jest test,
|
||||
```bash
|
||||
cd app/client
|
||||
|
||||
# Run either command below to run a test
|
||||
npx jest <file_path/file_name>
|
||||
|
||||
# or
|
||||
|
||||
yarn jest src/widgets/<filepath>/<filename>.test.ts --silent=false
|
||||
```
|
||||
|
||||
- To run a single jest test in watch mode,
|
||||
```bash
|
||||
npx jest --watch <file_path/file_name>
|
||||
```
|
||||
|
||||
### Windows WSL2 Setup
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user