Hello folks,

Let me quickly introduce you guys about Swirl before we start.

What is Swirl?

Swirl is an open-source search engine which is built using Python and Django. Things which makes Swirl more special is that individual developers and organizations can use Swirl without paying single penny and even customize the search results by connecting to Database (E.g. SQL, NoSQL), Public Data Services (E.g. Google) and Enterprise Sources (E.g. Jira).

GitHub Link: https://github.com/swirlai/swirl-search

Now that you know about Swirl, let's try and explore Swirl using Cloud IDE.

Table Of Contents

• Setting up Swirl using Gitpod
• Setting up Swirl using GitHub Codespaces
• Contributing to Swirl Community using Cloud IDE

Setting up Swirl using Gitpod

1. Click on below button to Configure New Workspace in Gitpod
   Alternatively, you can open Swirl Repo and prefix Swirl Repo URL with https://gitpod.io/new/# after which it looks something like this https://gitpod.io/#https://github.com/swirlai/swirl-search/tree/develop
   
   NOTE: Throughout this tutorial we will be working with Gitpod on the develop branch as per contribution guidelines of Swirl. If you intend to use the main branch, please use the following URL: https://gitpod.io/#https://github.com/swirlai/swirl-search/.

2. After opening the URL, we will see page as shown below:
   

3. Click on continue button to create and initialize Swirl Workspace.
   
   

4. We will observe that browser version of VScode getting configured. And in terminal, this command docker-compose pull && docker-compose up will start running.
   

5. After few seconds, we can observe INFO Listening on TCP 0.0.0.0:8000 log in the terminal.
   

6. Now our server is ready to serve the incoming requests on port 8000, as we are using Gitpod it will generates a dynamic URL for accessing content on port 8000 instead of localhost:8000 as we would in local development environment.
   To open this URL in browser, we can click on open browser button through notifications popup as shown below:
   Alternatively, we can navigate to PORTS tab next to Terminal and click on link provided in the Address column for Port 8000.
   

7. Oops, we encountered an error,
   let's check terminal logs to know more about error in VScode
   Seems like the dynamic URL which Gitpod generated is not allowed to request our server.

8. Now we need to make sure that our server accepts requests from our dynamic URL, we can fix this by creating .env file
   .env file should be created in root directory of the project as shown below:
   
   And add this line in .env file ALLOWED_HOSTS=localhost,127.0.0.1,*
* in ALLOWED_HOSTS mean is that we are allowing every host to access our server.
   

9. Now that we created .env file, we need to inform docker to use this configuration.
   Open docker-compose.yaml and add following line at the end:
   

    env_file:
      - .env

This is how it looks after we add above lines

As we have changed docker-compose.yaml we need to restart our server for changes to reflect.
To stop the server press CTRL+C key.
To start the server enter docker-compose pull && docker-compose up command in terminal.
Follow Steps 4-6 to check if the URL is working.

NOTE: While committing changes do not stage docker-compose.yaml file.

Setting up Swirl using GitHub Codespaces

1. Click on below link to open Swirl Repository in develop branch https://github.com/swirlai/swirl-search/tree/develop. NOTE: We will be working with GitHub Codespaces on the develop branch as per contribution guidelines of Swirl. If you intend to use the main branch, please use the following URL: https://github.com/swirlai/swirl-search/.
2. To create New Codespace on develop branch follow below steps:
   1. Click on Code button, which will open dropdown menu containing two tabs in it, namely Local and Codespaces.
   2. Then select Codespaces tab.
   3. Finally, click on the Create codespace on develop button to initiate the creation of codespace.
3. We will observe that browser version of VScode getting configured. In the terminal, the installation of pip and others requirements will start. After which docker-compose pull && docker-compose up command will start running.
4. Now inorder to view logs of the server, press CTRL+SHIFT+P key to open command palette and then search for View Creation log. We can notice new terminal with logs of our server.
5. After few seconds, we can observe INFO Listening on TCP 0.0.0.0:8000 log in the terminal.
6. Now our server is ready to serve the incoming requests on port 8000, as we are using GitHub Codespaces it will generates a dynamic URL for accessing content on port 8000 instead of localhost:8000 as we would in local development environment. We can navigate to PORTS tab next to Terminal and click on browser icon after hovering on link provided in the Address column for Port 8000.
7. In browser, you can observe Swirl login page with Username and Password fields. Enter Username as admin and Password as Password

Contributing to Swirl Community using Cloud IDE

Using Codespaces

1. Create a new terminal by clicking on + button.
2. Enter git fetch command to get changes from remote repo.
3. Now that you are will to contribute to Swirl we need create a new branch and switch to it, to do this use git checkout -b your-branch-name.
4. Do the changes accordingly and to check which files you created/modified use git status.
5. To stage all the changes use git add . and to commit the changes use git commit -m "your commit message".
6. You will see a warning that you don't have write access to swirl repo and to get access we need to create a fork. Github will create use fork after we enter y for Would you like to proceed question.
7. To push the branch with changes use git push origin your-branch-name. After successfully pushing the changes you will get URL in terminal to create pull request(PR), copy it and paste in new tab.
8. By default base repository comparing branch is main change it to develop branch by clicking on it.
9. Finally edit the PR template accordingly based on your changes.

Using Gitpod

1. Create a new terminal by clicking on + button.
2. Enter git fetch command to get changes from remote repo.
3. Now that you are will to contribute to Swirl we need create a new branch and switch to it, to do this use git checkout -b your-branch-name.
4. Do the changes accordingly and to check which files you created/modified use git status. NOTE: Do not stage docker-compose.yaml file.
5. To stage all the changes use git add . and to unstage docker-compose.yaml file use git reset -- docker-compose.yaml and to commit the changes use git commit -m "your commit message".

6. To push the changes, we need to grant GitHub access for Gitpod by following below steps:

   1. Navigate to Source Control by clicking on git logo on side panel.
   2. Finally, click on horizontal three-dots button.
   3. Click on push button in the dropdown.
   4. We will get a popup about remote repo, now click on ok to publish newly created branch as shown below
   5. We will get another popup whether to create fork of the repository click on Create_Fork.
   6. Allow GitHub extension to sign in.
   7. Click on Open Access Control button in the Grant permissions notifications.
   8. A new tab will open, displaying Gitpod User settings.
   9. Click on three vertical dots button present in GitHub row to edit permissions.
   10. Now checkmark on read:user,repo and workflow and click on update permissions.
   11. Now enter git push origin your-branch-name. From here follow Steps 7-9 from Contribution using Codespaces

Conclusion

With the help of Gitpod and GitHub Codespaces we were able to run instantly Swirl Search with minimal commands and without the need of any installation.

Special Mentions: Thank you @srbhr for your support and guidance.

GitHub: GitHub Repository🧑‍💻

Slack Community: Swirl Slack Community💬📢

Twitter: Follow Swirl on Twitter/𝕏