eser.live web site

Project Description

This codebase contains all the necessary code to operate the eser.live website. Since there's no hidden parts -excluding some API keys- and it's completely open-source, it simply allows you to modify it or run your own website by following the instructions below.

Additionally, this repository serves as a template for a full-stack web application built with Deno Fresh and Tailwind CSS.

Components

• Deno's built-in formatter, linter and test runner and TypeScript support
• Next-gen web framework with Fresh
• Data persistence with Drizzle ORM
• Modern CSS framework with Tailwind CSS
• UI components with Daisy UI
• Pre-commit hooks with pre-commit

Get Started

Get Started Locally

Before starting, you'll need:

• A GitHub account
• The Deno CLI and Git installed on your machine

To get started:

1. Clone this repo:

   git clone https://github.com/eser/eser.live.git
   cd eser.live

2. Create a new .env file:

   POSTGRES_CONNSTR=postgres://postgres:s3cr3t@0.0.0.0:5432/postgres
   GITHUB_CLIENT_ID=
   GITHUB_CLIENT_SECRET=
   

3. Navigate to GitHub's New OAuth Application page.
4. Set Application name to your desired application name. E.g. ACME, Inc.
5. Set Homepage URL to http://localhost:8000.
6. Set Authorization callback URL to http://localhost:8000/auth/callback.
7. Click Register application.
8. Copy the Client ID value to the .env file:

   GITHUB_CLIENT_ID=<GitHub OAuth application client ID>

9. On the same web page, click Generate a new client secret.
10. Copy the Client secret value to the .env file on a new line:

    GITHUB_CLIENT_SECRET=<GitHub OAuth application client secret>

11. Start the server:

    deno task start

12. Navigate to http://localhost:8000 to start playing with the app.

Bootstrap the Database

Use the following commands to work with your local database:

• deno task db:migrate - Populate the database with data.
• deno task db:reset - Reset the database. This is not recoverable.

Customize and Extend

Global Constants

The ./pkg/main/constants.ts file includes global values used across various aspects of the codebase. Update these values according to your needs.

Create a Blog Post

1. Create a .md file in the ./content/posts with the filename as the slug of the blog post URL. E.g. a file with path /content/posts/20240620-hello-there.md will have path /blog/20240620-hello-there.

2. Write the Front Matter then Markdown text to define the properties and content of the blog post.

   ---
   title: This is my first blog post!
   publishedAt: 2024-06-20T15:00:00.000Z
   summary: This is an excerpt of my first blog post.
   ---
   
   # Heading 1
   
   Hello, world!
   
   ```javascript
   console.log("Hello World");
   ```

3. Start the server:

   deno task start

4. Navigate to the URL of the newly created blog post. E.g. http://localhost:8000/blog/20240620-hello-there.

See other examples of blog post files in ./content/posts.

Stylesheets

You can create and customize styles within the capabilities of Tailwind CSS and Daisy UI. Tailwind configuration can be found at ./pkg/main/tailwind.config.ts.

Deploy to Production

This section assumes that a local development environment is already set up.

1. Navigate to your GitHub OAuth application settings page.
2. Set the Homepage URL to your production URL. E.g. https://eser.live.
3. Set the Authorization callback URL to your production URL with the /auth/callback path. E.g. https://eser.live/auth/callback.
4. Copy all the environment variables in your .env file to your production environment.

Deploy to Deno Deploy

1. Clone this repository.
2. Sign into Deno Deploy with your GitHub account.
3. Select your GitHub organization or user, repository, and branch.
4. Select Automatic deployment mode and main.ts as the entry point.
5. Click Link, which will start the deployment.
6. Once the deployment is complete, click on Settings and add the production environmental variables, then hit Save.

You should now be able to visit your newly deployed SaaS.

Deploy to any VPS with Docker

Docker makes it easy to deploy and run your Deno app to any virtual private server (VPS). This section will show you how to do that with AWS Lightsail and Digital Ocean.

1. Install Docker on your machine, which should also install the docker CLI.
2. Create an account on Docker Hub, a registry for Docker container images.

Note: the Dockerfile, .dockerignore and docker-compose.yml files come included with this repo.

1. Grab the SHA1 commit hash by running the following command in the repo's root folder:

# get the SHA1 commit hash of the current branch
git rev-parse HEAD

1. Copy the output of the above and paste it as DENO_DEPLOYMENT_ID in your .env file. This value is needed to enable caching on Fresh in a Docker deployment.

2. Finally, refer to these guides for using Docker to deploy Deno to specific platforms:

• Amazon Lightsail
• Digital Ocean
• Google Cloud Run

REST API Reference

GET /api/questions

Get all questions in chronological order. Add ?cursor=<cursor> URL parameter for pagination. Limited to 10 questions per page.

Example 1:

// https://eser.live/api/questions
{
  "items": [
    // 9 more items...
    {
      "id": "01HRRK8DNTDEX83265MX9G2MHD",
      "userLogin": "eser",
      "question": "Test sorusu",
      "score": 1,
      "hidden": false
    }
  ],
  "cursor": "01HRRK8DNTDEX83265MX9G2MHD"
}

Example 2 (using cursor field from page 1):

// https://eser.live/api/questions?cursor=01HRRK8DNTDEX83265MX9G2MHD
{
  "items": [
    // 7 more items...
  ],
  "cursor": ""
}

GET /api/questions/:id

Get the question with the given ID.

Example:

// https://eser.live/api/questions/01HRRK8DNTDEX83265MX9G2MHD
{
  "id": "01HRRK8DNTDEX83265MX9G2MHD",
  "userLogin": "eser",
  "question": "Test sorusu",
  "score": 1,
  "hidden": false
}

GET /api/users

Get all users in alphabetical order by GitHub login. Add ?cursor=<cursor> URL parameter for pagination. Limited to 10 users per page.

Example:

// https://eser.live/api/users
{
  "items": [
    {
      "login": "eser",
      "sessionId": "1b10cfe8-25c4-4d77-b999-0602fa1760cc"
    }
  ],
  "cursor": ""
}

GET /api/users/:login

Get the user with the given GitHub login.

Example:

// https://eser.live/api/users/eser
{
  "login": "eser",
  "sessionId": "1b10cfe8-25c4-4d77-b999-0602fa1760cc"
}

Acknowledgement, Goals and Philosophy

This codebase is a fork of Deno SaaSKit, we would like to thank the contributors and maintainers of the original project.

Our project maintains the same philosophy and goals of the original project, but with some modifications to fit the needs of the eser.live and the community around us.

For the user, the website should be fast, secure and have a design with clear intent. Additionally, the HTML should be well-structured and indexable by search engines. The defining metrics for these goals are:

• A perfect PageSpeed Insights score.
• Fully valid HTML, as measured by W3C's Markup Validation Service.

For the developer, the codebase should minimize the steps and amount of time required to get up and running. From there, customization and extension of the web app should be simple. The characteristics of a well-written codebase also apply, such as:

• Easy to understand
• Modular functionality
• Clearly defined behavior with validation through tests

Requirements

• Deno 1.44 or higher (https://deno.land/)
• pre-commit (https://pre-commit.com/)

Versioning

This project follows Semantic Versioning. For the versions available, see the tags on this repository.

Community and Resources

Join the #lobi channel in eser.live Discord to ask questions, and get unblocked.

License

This project is licensed under the MIT License. For further details, please see the LICENSE file.

To support the project...

Visit my GitHub Sponsors profile at github.com/sponsors/eser