diff --git a/docs/source/07-troubleshooting/support/faq.md b/docs/source/07-troubleshooting/support/faq.md index 5db1e39f74..b12f58d333 100644 --- a/docs/source/07-troubleshooting/support/faq.md +++ b/docs/source/07-troubleshooting/support/faq.md @@ -4,44 +4,44 @@ This section provides answers to common questions developers have while working ## Table of Contents -- [Setup & Installation](#setup-installation) -- [Docker & Frontend Issues](#docker-frontend-issues) -- [Python & Backend Errors](#python-backend-errors) -- [Development & Contribution](#development-contribution) -- [Logs & Debugging](#logs-debugging) -- [Command Node, npm & Frontend Issues](#common-node-npm-frontend-issues) -- [Proxy / Network Issues](#proxy-network-issues) +- [Setup & Installation](#setup--installation) +- [Docker & Frontend Issues](#docker--frontend-issues) +- [Python & Backend Errors](#python--backend-errors) +- [Development & Contribution](#development--contribution) - [PostgreSQL Errors](#postgresql-errors) - [Learning Resources](#learning-resources) - [Recommended Next Steps](#recommended-next-steps) +--- + ## Setup & Installation ### Q. How to start contributing? -EvalAI’s issue tracker is good place to start. If you find something that interests you, comment on the thread and we’ll help get you started. -Alternatively, if you come across a new bug on the site, please file a new issue and comment if you would like to be assigned. Existing issues are tagged with one or more labels, based on the part of the website it touches, its importance etc., which can help you select one. +EvalAI's issue tracker is good place to start. If you find something that interests you, comment on the thread and we'll help get you started. Alternatively, if you come across a new bug on the site, please file a new issue and comment if you would like to be assigned. Existing issues are tagged with one or more labels, based on the part of the website it touches, its importance etc., which can help you select one. ### Q. What are the technologies that EvalAI uses? -Please refer to [Technologies Used](https://evalai.readthedocs.io/en/latest/architecture.html) +Please refer to [Technologies Used](../../02-architecture/technologies.md) -### Q. Why was `virtualenv` setup deprecated? +### Q. Why was virtualenv setup deprecated? Due to evolving dependencies and environment complexity, we now recommend using Docker-based setup for reliability and consistency across systems. +--- + ## Docker & Frontend Issues -### Q. I see `Cannot GET \` on `http://localhost:8888/` when using Docker. +### Q. I see `Cannot GET \` on http://localhost:8888/ when using Docker. This may happen if the container is not built properly. Run: -``` +```bash docker compose down docker compose up --build ``` -### Q. I get this error: `ERROR: Version in "./docker-compose.yml" is unsupported`. +### Q. I get this error: `ERROR: Version in "./docker-compose.yml" is unsupported.` Upgrade your Docker engine to the latest version compatible with Compose file version 3. @@ -50,26 +50,18 @@ Upgrade your Docker engine to the latest version compatible with Compose file ve This usually happens due to cache. Clean your browser cache & cookies completely and try accessing the website again, if still doesn't work, then try on a new browser profile. ### Q. While building EvalAI via Docker, I get: + ``` ERROR: Service 'celery' failed to build: pull access denied for evalai_django, repository does not exist or may require 'docker login': denied: requested access to the resource is denied ``` -Ensure that your directory is named `evalai` (all lowercase). Docker image naming depends on the folder name. For instance, the image evalai_django gets renamed to evalai_dev_django if your directory is renamed to EvalAI_dev. +**Solution:** -## Python & Backend Errors - -### Q. I get this error during DB seeding: +Ensure that your directory is named `evalai` (all lowercase). Docker image naming depends on the folder name. For instance, the image `evalai_django` gets renamed to `evalai_dev_django` if your directory is renamed to `EvalAI_dev`. -```bash -Exception while running run() in 'scripts.seed' -``` - -Try deleting the PostgreSQL database manually or ensure you're using Python 2.7.x (not Python 3.x). - -### Q. I see `Peer authentication failed for user "postgres"` when using `createdb`. - -Try creating a new user and then grant all the privileges to it and then create a db. +--- +## Python & Backend Errors ### Q. I get this error while running tests inside Docker: @@ -77,120 +69,47 @@ Try creating a new user and then grant all the privileges to it and then create import file mismatch... ``` -Clean __pycache__ and .pyc files: +**Solution:** -``` +Clean `__pycache__` and `.pyc` files: + +```bash find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf ``` +--- + ## Development & Contribution ### Q. How do I fix coverage decrease warnings? This means your new code isn't covered by tests. Click on the coverage report to view uncovered lines and add test cases accordingly. -## Logs & Debugging - -### Q. How do I debug `psycopg2` installation errors while using `pip install -r dev/requirement.txt`? - -Error: - -``` -Error: You need to install postgresql-server-dev-X.Y... -``` - -Fix: - -``` -sudo apt-get install postgresql -sudo apt-get install python-psycopg2 -sudo apt-get install libpq-dev -``` - -## Common Node, npm & Frontend Issues - -### Q. `gulp: command not found` - -``` -npm install -g gulp-cli -``` - -### Q. `bower: command not found` - -``` -npm install -g bower -``` - -### Q. Mocha reporter not loading: - -``` -npm uninstall -g generator-karma -npm install -g generator-angular -``` - -### Q. Error: `Gem sass is not installed` while executing `gulp dev:runserver` - -``` -gem install sass -``` - -### Q. Getting `karma@>=0.9.0 but none was installed` while executing `npm install`: - -Reinstall after removing cache: - -``` -npm uninstall karma -npm install karma -npm cache clean --force -``` - -### Q. Getting: - -``` -/usr/lib//nodejs/gulp//bin/gulp.js:132 -TypeError: Cannot read properly 'apply of undefined' -``` - -Fix: - -``` -rm -rf node_modules/ bower_components -npm install -bower install -``` - -## Proxy / Network Issues - -### Q. npm install fails with ECONNRESET or tunneling error - -Fix your proxy settings: - -``` -npm config delete proxy -npm config delete https-proxy -npm config set registry https://registry.npmjs.org/ -``` +--- ## PostgreSQL Errors ### Q. ERROR: Port 5432 already in use +**Solution:** + Check and kill the process: -``` +```bash sudo netstat -lpn | grep :5432 sudo kill ``` +--- + ## Learning Resources - [Git and GitHub Learning Resources](https://help.github.com/articles/git-and-github-learning-resources/) - - [Markdown Guide](https://guides.github.com/features/mastering-markdown/) +--- ## Recommended Next Steps -- Refer to the [EvalAI Docs](https://evalai.readthedocs.io/en/latest/) - -- [Join our Slack](https://join.slack.com/t/cloudcv-community/shared_invite/zt-3252n6or8-e0QuZKIZFLB0zXtQ6XgxfA) to ask for help if you're stuck +- Refer to the [EvalAI Docs](https://evalai.readthedocs.io/) +- Join our [Slack](https://evalai.cloudcv.org/web/slack) to ask for help if you're stuck \ No newline at end of file diff --git a/docs/source/faq(developers).md b/docs/source/faq(developers).md index b3c597d205..47d731442e 100644 --- a/docs/source/faq(developers).md +++ b/docs/source/faq(developers).md @@ -1,269 +1,128 @@ -## Frequently Asked Questions +# Frequently Asked Questions -#### Q. How to start contributing? +This guide provides answers to common questions developers have while working with EvalAI. -EvalAI’s issue tracker is good place to start. If you find something that interests you, comment on the thread and we’ll help get you started. -Alternatively, if you come across a new bug on the site, please file a new issue and comment if you would like to be assigned. Existing issues are tagged with one or more labels, based on the part of the website it touches, its importance etc., which can help you select one. +## Table of Contents -#### Q. What are the technologies that EvalAI uses? +- [General Development](#general-development) +- [Docker & Setup Issues](#docker--setup-issues) -Please refer to [Technologies Used](https://evalai.readthedocs.io/en/latest/architecture.html) +--- -#### Q. Where could I learn GitHub Commands? +## General Development -Refer to [GitHub Guide](https://help.github.com/articles/git-and-github-learning-resources/). - -#### Q. Where could I learn Markdown? - -Refer to [Markdown Guide](https://guides.github.com/features/mastering-markdown/). - -#### Q. What to do when coverage decreases in your pull request? - -Coverage decreases when the existing test cases don't test the new code you wrote. If you click coverage, you can see exactly which all parts aren't covered and you can write new tests to test the parts. - -#### Q. How to setup EvalAI using virtualenv? - -We have removed the documentation for setting up using virtual environment since the project has grown and different developers face different dependency issues. We recommend to setup EvalAI using docker based environment. - -### Common Errors during installation - -#### Q. While using `pip install -r dev/requirement.txt` - -``` - Writing manifest file 'pip-egg-info/psycopg2.egg-info/SOURCES.txt' - Error: You need to install postgresql-server-dev-X.Y for building a server-side extension or - libpq-dev for building a client-side application. - ---------------------------------------- - Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-build-qIjU8G/psycopg2/ -``` - -Use the following commands in order to solve the error: - -1. `sudo apt-get install postgresql` -2. `sudo apt-get install python-psycopg2` -3. `sudo apt-get install libpq-dev` - -#### Q. While using `pip install -r dev/requirement.txt` - -``` -Command “python setup.py egg_info” failed with error code 1 in -/private/var/folders/c7/b45s17816zn_b1dh3g7yzxrm0000gn/T/pip-build- GM2AG/psycopg2/ -``` - -Firstly check that you have installed all the mentioned dependencies. -Then, Upgrade the version of postgresql to 10.1 in order to solve it. +### Q. How to start contributing? -#### Q. Getting an import error +EvalAI’s issue tracker is good place to start. If you find something that interests you, comment on the thread and we’ll help get you started. Alternatively, if you come across a new bug on the site, please file a new issue and comment if you would like to be assigned. Existing issues are tagged with one or more labels, based on the part of the website it touches, its importance etc., which can help you select one. -``` -Couldn't import Django,"when using command python manage.py migrate -``` - -Firstly, check that you have activated the virtualenv. -Install python dependencies using the following commands on the command line - -``` -cd evalai -pip install -r requirements/dev.txt -``` - -#### Q. Getting Mocha Error - -``` -Can not load reporter “mocha”,it is not registered -``` - -Uninstall karma and then install +### Q. What are the technologies that EvalAI uses? -``` -npm uninstall -g generator-karma && npm install -g generator-angular. -``` - -#### Q. While trying to execute `bower install` - -``` -bower: command not found -``` +Please refer to [Technologies Used](../02-architecture/technologies.md) -Execute the following command first : +### Q. Where could I learn GitHub Commands?nds? -``` -npm install -g bower -``` - -#### Q. While trying to execute `gulp dev:runserver` - -``` -gulp: command not found -``` - -Execute the following command first - -``` -npm install -g gulp-cli -``` - -#### Q. While executing `gulp dev:runserver` - -``` -events.js:160 -throw er; // Unhandled 'error' event -^ -Error: Gem sass is not installed. -``` - -Execute the following command first : +Refer to [GitHub Guide](https://help.github.com/articles/git-and-github-learning-resources/). -``` -gem install sass -``` +### Q. Where could I learn Markdown? -#### Q. While trying to install `npm config set proxy http://proxy:port` on Ubuntu, I get the following error: +Refer to [Markdown Guide](https://guides.github.com/features/mastering-markdown/). -``` -ubuntu@ubuntu-Inspiron-3521:~/Desktop/Python-2.7.14$ npm install -g angular-cli -npm ERR! Linux 4.4.0-21-generic -npm ERR! argv "/usr/bin/nodejs" "/usr/bin/npm" "install" "-g" "angular-cli" -npm ERR! node v4.2.6 -npm ERR! npm v3.5.2 -npm ERR! code ECONNRESET - -npm ERR! network tunneling socket could not be established, cause=getaddrinfo ENOTFOUND proxy proxy:80 -npm ERR! network This is most likely not a problem with npm itself -npm ERR! network and is related to network connectivity. -npm ERR! network In most cases you are behind a proxy or have bad network settings. -npm ERR! network -npm ERR! network If you are behind a proxy, please make sure that the -npm ERR! network 'proxy' config is set properly. See: 'npm help config' - -npm ERR! Please include the following file with any support request: -npm ERR! /home/ubuntu/Desktop/Python-2.7.14/npm-debug.log -``` +### Q. What to do when coverage decreases in your pull request? -To solve, execute the following commands: +Coverage decreases when the existing test cases don't test the new code you wrote. If you click coverage, you can see exactly which all parts aren't covered and you can write new tests to test the parts. -1. `npm config set registry=registry.npmjs.org` +### Q. How to setup EvalAI using virtualenv? -If the above does not work, try deleting them by following commands: +We have removed the documentation for setting up using virtual environment since the project has grown and different developers face different dependency issues. We recommend to setup EvalAI using docker based environment. -1. `npm config delete proxy` -2. `npm config delete https-proxy` +--- -Then, start the installation process of frontend once more. +## Docker & Setup Issues -#### Q. While using docker, I am getting the following error on URL [http://localhost:8888/](http://localhost:8888/): +### Q. While using docker, I am getting the following error on URL http://localhost:8888/: ``` Cannot Get \ ``` -Try removing the docker containers and then building them again. +**Solution:** -#### Q. Getting the following error while running `python manage.py seed`: +Try removing the docker containers and then building them again: +```bash +docker compose down +docker compose up --build ``` -Starting the database seeder. Hang on... Exception while running run() in 'scripts.seed' Database successfully seeded -``` - -Change the python version to 2.7.x . The problem might be because of the python 3.0 version. -#### Q. Getting the following error while executing command `createdb evalai -U postgres`: - -``` -createdb: could not connect to database template1: FATAL: Peer authentication failed for user "postgres" -``` - -Try creating a new user and then grant all the privileges to it and then create a db. - -#### Q. Getting the following error while executing `npm install`: - -``` -npm WARN generator-angular@0.16.0 requires a peer of generator- -karma@>=0.9.0 but none was installed. -``` - -Uninstall and then install karma again and also don't forget to clean the global as well as project npm cache. Then try again the step 8. - -#### Q. While running the unit tests, I am getting the error similar to as shown below: +### Q. While running the unit tests, I am getting the error similar to as shown below: ``` ________________ ERROR collecting tests/unit/web/test_views.py _________________ import file mismatch: -imported module 'tests.unit.web.test_views' has this __file__ attribute: +imported module 'tests.unit.web.test_views' has this file attribute: /path/to/evalai/tests/unit/web/test_views.py which is not the same as the test file we want to collect: /code/tests/unit/web/test_views.py HINT: remove __pycache__ / .pyc files and/or use a unique basename for your test file modules ``` -It appears that you are trying to run `pytest` in a docker container. To fix this, delete the `__pycache__` and all `*.pyc` files using the following command: - -`find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf` +**Solution:** -#### Q. Getting the following error: +It appears that you are trying to run pytest in a docker container. To fix this, delete the `__pycache__` and all `*.pyc` files using the following command: +```bash +find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf ``` -ERROR: for db Cannot start service db: driver failed programming external connectivity on endpoint evalai_db_1 (2163096de9aac6561b4f699bb1049acd0ce881fbaa0da28e47cfa9ca0ee1199f): Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use -``` - -The following solution only works on Linux. -Execute : -`sudo netstat -lpn |grep :5432` - -The output of the above would be in the following form: +### Q. Getting the following error:ror: ``` -tcp 0 0 127.0.0.1:5432 0.0.0.0:* LISTEN 25273/postgres +ERROR: for db Cannot start service db: driver failed programming external connectivity +on endpoint evalai_db_1 (2163096de9aac6561b4f699bb1049acd0ce881fbaa0da28e47cfa9ca0ee1199f): +Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use ``` -Execute the following command: +**Solution:** -``` -sudo kill 25273 ## This would vary and you can change with the output in the first step -``` +> **Note:** The following solution only works on Linux. -#### Q. Getting the following error when using Docker: +1. Execute: -``` -ERROR : Version in "./docker-compose.yml" is unsupported. You might be seeing this error because you are using wrong Compose file version. -``` + ```bash + sudo netstat -lpn | grep :5432 + ``` -Since, the version of compose file is 3. You might be using a docker version which is not compatible. You can upgrade your docker engine and try again. +2. The output of the above would be in the following form: -#### Q. Getting the following error while running `python manage.py runserver --settings=settings.dev`: + ``` + tcp 0 0 127.0.0.1:5432 0.0.0.0:* LISTEN 25273/postgres + ``` -``` -Starting the database seeder. Hang on... -Are you sure you want to wipe the existing development database and reseed it? (Y/N) -Exception while running run() in 'scripts.seed' -``` +3. Execute the following command: -Try clearing the postgres database manually and try again. + ```bash + sudo kill 25273 # Replace 25273 with the PID from step 1 + ``` -#### Q. Getting the following error while executing `gulp dev:runserver`: +### Q. Getting the following error when using Docker:ker: ``` -/usr/lib//nodejs/gulp//bin/gulp.js:132 - gulpInst.start.apply(gulpInst, toRun)l - ^ -TypeError: Cannot read properly 'apply of undefined' +ERROR: Version in "./docker-compose.yml" is unsupported. +You might be seeing this error because you are using wrong Compose file version. ``` -Execute the following command: +**Solution:** -``` -rm -rf node_modules/ -rm -rf bower_components -npm install -bower install -``` +Since the version of compose file is 3, you might be using a docker version which is not compatible. You can upgrade your docker engine and try again. -#### Q. While trying to build EvalAI from the master branch and run the command docker-compose up: +### Q. While trying to build EvalAI from the master branch and run the command `docker-compose up`: ``` -ERROR: Service 'celery' failed to build: pull access denied for evalai_django, repository does not exist or may require 'docker login': denied: requested access to the resource is denied +ERROR: Service 'celery' failed to build: pull access denied for evalai_django, +repository does not exist or may require 'docker login': denied: requested access +to the resource is denied ``` -Please make sure to clone EvalAI in its default directory with name evalai. This happens because the parent directory changes the name of docker images. -For instance, the image evalai_django gets renamed to evalai_dev_django if your directory is renamed to EvalAI_dev. +**Solution:** + +Please make sure to clone EvalAI in its default directory with name `evalai` (all lowercase). This happens because the parent directory changes the name of docker images. For instance, the image `evalai_django` gets renamed to `evalai_dev_django` if your directory is renamed to `EvalAI_dev`. \ No newline at end of file