UCSBOrganization: Dokku Dev Deployment Guide

by Admin 45 views
UCSBOrganization: Your Guide to Creating a Personal Dokku Dev Deployment

Hey guys! Let's dive into setting up your personal Dokku development environment for the UCSBOrganization project. This is a crucial step for getting your hands dirty with the codebase and testing your changes. This comprehensive guide will walk you through each step, ensuring you have a smooth setup process. We'll cover everything from creating your app to configuring Google OAuth, so stick around!

Dependencies

Good news! There are no dependencies for this task. If you're the team member tackling UCSBOrganization, this is your starting point. Let's get the ball rolling!

Overview

The primary goal here is to create your personal Dokku deployment, which will serve as your sandbox for developing and testing features for UCSBOrganization. This ensures that you have an isolated environment where you can experiment without affecting the main application. Think of it as your personal playground where you can build and break things without worry. This issue is designed to help you track the creation of your personal Dokku deployment, making sure every step is completed.

Acceptance Criteria

To ensure we're all on the same page, here's a checklist of what needs to be accomplished. Make sure you tick off each item as you go:

  • [ ] App Creation: You need to create an app named <tt>team02-YOURGITHUBID-dev</tt> on the team's Dokku server. Replace YOURGITHUBID with your actual GitHub ID. This naming convention helps keep things organized.
  • [ ] Database Configuration: Configure a database for your newly created app. The documentation at https://ucsb-cs156.github.io/topics/dokku/postgres_database.html will guide you through this process. Think of the database as the storage center for all your application's data.
  • [ ] Admin Email Configuration: Set up the ADMIN_EMAILS for your app. You'll find the necessary email addresses in a pinned post on your team's Slack channel. Instructions for configuring this variable can be found here: https://ucsb-cs156.github.io/topics/dokku/environment_variables.html. This step is crucial for ensuring that the right people have administrative access.
  • [ ] Google OAuth Configuration: This involves two main steps:
  • [ ] Team Access Verification: Ensure that everyone on the team, including the instructor and TAs, can log in with OAuth and verify that they have admin privileges. This is a critical step to confirm that your authentication setup is working correctly.
  • [ ] Initial Deployment: Deploy the main branch initially and confirm that it works as expected. This serves as a baseline. Later, you'll deploy your own branches to this instance for testing before merging. Deploying the main branch first ensures that your environment is set up correctly before you start making changes.
  • [ ] HTTPS Configuration: Configure HTTPS for your app. The instructions are available at https://ucsb-cs156.github.io/topics/dokku/enabling_https.html. HTTPS is essential for securing the communication between your app and its users.

Breaking Down the Acceptance Criteria: A Detailed Look

Let's zoom in and discuss each acceptance criterion in detail, making sure you understand the significance and how to tackle it.

1. App Creation: <tt>team02-YOURGITHUBID-dev</tt>

First off, creating the app with the specified naming convention is more than just a formality; it's about maintaining order and clarity within the team's Dokku server. This naming pattern, team02-YOURGITHUBID-dev, instantly tells anyone looking at the server which team the app belongs to, whose personal development environment it is, and that it's a development instance. Replacing YOURGITHUBID with your actual GitHub username is crucial for this system to work effectively. This step ensures that your application has a dedicated space on the Dokku server, separate from other team members, which is vital for preventing conflicts and ensuring a smooth development process.

2. Database Configuration

Next up, configuring a database for your app. Think of the database as the backbone of your application; it's where all the data lives. Without a properly configured database, your application won't be able to store or retrieve information, making it essentially non-functional. The guide at https://ucsb-cs156.github.io/topics/dokku/postgres_database.html is your best friend here. It provides a step-by-step walkthrough of how to set up a PostgreSQL database, which is a powerful and reliable choice for most web applications. This involves creating a new database within your Dokku environment and linking it to your application. The database configuration is a fundamental aspect of your development environment, and getting it right from the start will save you headaches down the road.

3. Admin Email Configuration

Setting up ADMIN_EMAILS is about granting administrative privileges and ensuring that the right people have the keys to the kingdom. In a collaborative project like this, there are individuals who need higher-level access to manage the application, handle user issues, and oversee the system's overall health. These individuals typically include the team members leading the development, the instructor, and the teaching assistants (TAs). The admin emails are usually found in a pinned post on your team's Slack channel, so make sure you check there first. Configuring this variable involves setting an environment variable in your Dokku application that lists these email addresses. You'll find detailed instructions on how to do this at https://ucsb-cs156.github.io/topics/dokku/environment_variables.html. This ensures that when admin-level actions are required within the application, the correct people are notified and have the necessary access.

4. Google OAuth Configuration

Google OAuth (Open Authentication) integration is a modern and secure way to handle user authentication. Instead of requiring users to create yet another username and password, OAuth allows them to log in using their existing Google accounts. This not only simplifies the login process for users but also enhances security. Configuring Google OAuth involves two main steps. First, you need to set up OAuth credentials within the Google Developer Console. The guide at https://ucsb-cs156.github.io/topics/oauth/oauth_google_setup.html provides a detailed walkthrough of this process, including how to create a new project, enable the necessary APIs, and generate the client ID and client secret. Once you have these credentials, you need to configure them within your Dokku application as environment variables. This is where the second step comes in, using the instructions at https://ucsb-cs156.github.io/topics/dokku/environment_variables.html to set the GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. Correctly configuring Google OAuth is crucial for a seamless and secure user experience.

5. Team Access Verification

After setting up Google OAuth, the next vital step is to verify that everyone on the team, including the instructor and TAs, can log in successfully and that they are recognized as administrators within the application. This is a crucial test to ensure that your authentication setup is working as expected and that everyone who needs admin privileges has them. Have each team member attempt to log in using their Google account and then check that their account is recognized as an administrator within the application's interface. If anyone is unable to log in or does not have the correct privileges, it's essential to troubleshoot the OAuth configuration until everyone has access. This verification step is a key safeguard against access issues down the line.

6. Initial Deployment of the main Branch

Deploying the main branch initially serves as a crucial baseline. It's like checking that all the pieces of your puzzle fit together before you start rearranging them. By deploying the main branch, you're confirming that your Dokku environment is correctly set up and that the core application functionality is working as expected. This step helps you identify any issues with your deployment process or environment setup early on, before you start making changes. If the main branch doesn't deploy correctly, it indicates a problem with your environment configuration, which you can then address before proceeding. Once you've confirmed that the main branch is running smoothly, you can be confident that your development environment is ready for your customizations.

7. HTTPS Configuration

Finally, configuring HTTPS (Hypertext Transfer Protocol Secure) for your app is all about security. HTTPS encrypts the communication between your app and its users, protecting sensitive information like passwords and personal data from being intercepted. This is especially important for web applications that handle user accounts or sensitive data. The guide at https://ucsb-cs156.github.io/topics/dokku/enabling_https.html provides a detailed walkthrough of how to set up HTTPS for your Dokku application, typically involving the use of Let's Encrypt, a free, automated, and open certificate authority. Enabling HTTPS is a critical step in ensuring the security and privacy of your application's users.

By methodically working through each of these steps, you'll establish a robust and secure development environment for your UCSBOrganization project, which will greatly facilitate your development efforts.

What to do next

Alright, you've conquered the setup! What's next on the agenda? Let's keep the momentum going:

  • Move the Issue: Drag the issue for "UCSBOrganization - Create personal dokku dev deployment" directly into the "Done" column. Setup tasks like these don't require code review, so you're good to go!

  • Locate the Next Issue: Find the issue titled "Copy files for Backend CRUD API UCSBOrganization from team01" on the Kanban board. Yes, you read that right – team01! Even though you're on team02, the next step involves borrowing some files from team01. Don't worry; it's all part of the plan.

  • Assign and Start: Assign that issue to yourself and drag it into the "In Progress" column. It's time to dive into some code!

  • Create a New Branch: Start a new branch for your work. A good naming convention is something like xy-UCSBOrganization-backend, where xy are your initials. This helps keep your branches organized.

    Here's the Git magic to make it happen:

    git fetch
git checkout main
git pull origin main
git checkout -b _your-branch-name_

    Replace _your-branch-name_ with your chosen branch name. This ensures you're working on the latest version of the codebase and that your changes are isolated.

So, there you have it! You've successfully set up your personal Dokku dev deployment and are ready to tackle the next challenge. Keep up the great work, and remember to reach out if you have any questions. Happy coding! 🚀