From 0db3cf0e5d8f6e27b5c4afe08251db11c5e6d4bb Mon Sep 17 00:00:00 2001 From: mcnaveen <8493007+mcnaveen@users.noreply.github.com> Date: Wed, 2 Oct 2024 20:32:14 +0530 Subject: [PATCH] docs(docs): :memo: update the docs for development setup --- .env.example | 2 +- CONTRIBUTING.md | 2 ++ README.md | 6 +++- docs/development.md | 54 +++++++++++++++++++++++++++++++++ docs/generate-github-secrets.md | 16 ++++++++++ docs/installation.md | 10 +++--- docs/use-supabase.md | 24 +++++++++++++++ 7 files changed, 108 insertions(+), 6 deletions(-) create mode 100644 docs/development.md create mode 100644 docs/generate-github-secrets.md create mode 100644 docs/use-supabase.md diff --git a/.env.example b/.env.example index 07beb91..e127924 100644 --- a/.env.example +++ b/.env.example @@ -39,4 +39,4 @@ EMAIL_SERVER_PORT= EMAIL_FROM= # Set to true if you are self-hosting the app, this will set the first user to be an admin of the instance -SELFHOSTED= +SELFHOSTED=true \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5f3bca..f9b9f18 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,8 @@ There are several ways you can contribute to the Liny project: - Create a new branch for your changes - Submit a pull request for your changes + > Detailed steps are available in the [Development Guide](./docs/development.md). + 4. **Improving Documentation**: You can help improve the project's documentation by correcting errors, adding new content, or enhancing existing documentation. 5. **Providing Feedback or Suggestions**: You can share your feedback, ideas, or suggestions for the project by participating in the [Discord server](https://discord.gg/Wz2B3wQZCZ). diff --git a/README.md b/README.md index 4ea4023..fca8e18 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,11 @@ Liny is an open-source customer feedback management platform, designed as an alt ## Getting Started -To get started with Liny, please follow the instructions in the [Installation Guide](https://github.com/mcnaveen/liny/blob/dev/docs/INSTALLATION.md). +To get started with Liny, please follow the instructions in the [Installation Guide](https://github.com/mcnaveen/liny/blob/dev/docs/installation.md). + +## Development + +To spin up the development server, please follow the instructions in the [Development Guide](https://github.com/mcnaveen/liny/blob/dev/docs/development.md). ## Contributing diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..75b32ab --- /dev/null +++ b/docs/development.md @@ -0,0 +1,54 @@ +## Development Instructions + +### Prerequisites + +- Node.js +- Package Manager (pnpm or npm or yarn) +- Git +- Database (PostgreSQL, MySQL or You can use Supabase) +- GitHub OAuth Credentials (Client ID and Client Secret) [Generate GitHub Secrets](./generate-github-secrets.md) + +### Setting up the project + +1. Go to the [GitHub Releases](https://github.com/mcnaveen/liny/) and Click on the `Fork` button. +2. Clone the repository: + + ```bash + git clone https://github.com/YOUR_USERNAME/liny.git + cd liny + ``` + +3. Install the dependencies: + + ```bash + pnpm install + ``` + + > Alternatively, you can use `npm` or `yarn` to install the dependencies. + +4. Copy the example environment file and configure it: + + ```bash + cp .env.example .env + ``` + +5. Open the `.env` file and fill in the required fields. You can leave the SMTP fields empty if not needed. + +| Required Fields | Description | +| ---------------------- | ---------------------------------------------- | +| `DATABASE_URL` | You can use local database or Supabase | +| `NEXTAUTH_SECRET` | (You can use any random string for this) | +| `NEXTAUTH_URL` | (You can use `http://localhost:3000` for this) | +| `NEXT_PUBLIC_APP_URL` | (You can use `http://localhost:3000` for this) | +| `GITHUB_CLIENT_ID` | Required to use GitHub OAuth | +| `GITHUB_CLIENT_SECRET` | Required to use GitHub OAuth | + +> (If you're using Supabase, please refer to the [Supabase Setup Guide](./use-supabase.md) and come back. Otherwise, you can use any other database supported by Prisma [MySQL, PostgreSQL, etc.].) + +> Refer to [Generate a GitHub Secret](./generate-github-secrets.md) to generate the `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`. + +6. If you're self-hosting, set `SELFHOSTED` to `true` in the `.env` file to block other users from creating projects in your instance. (Default is `true`) + +7. Run `npx prisma db push` to create the tables. + +8. Run `pnpm run dev` to start the development server. diff --git a/docs/generate-github-secrets.md b/docs/generate-github-secrets.md new file mode 100644 index 0000000..150f4fb --- /dev/null +++ b/docs/generate-github-secrets.md @@ -0,0 +1,16 @@ +## Generate GitHub Secrets + +1. Go to the [GitHub -> Settings -> Developer settings -> OAuth Apps](https://github.com/settings/developers) +2. Click on "New OAuth App" +3. Fill in the required fields: + - Application name: "Liny" + - Homepage URL: "http://localhost:3000" + - Authorization callback URL: "http://localhost:3000/api/auth/callback/github" +4. Click on "Register application" +5. Copy the "Client ID" + +6. Click on "Generate a new client secret" +7. Copy the "Client Secret" + +- If you're using a different port, make sure to update the callback URL. +- If you're running the app in production, make sure to update the homepage URL and callback URL to `https://YOURDOMAIN.com/api/auth/callback/github` diff --git a/docs/installation.md b/docs/installation.md index e46c906..9316f38 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -17,7 +17,7 @@ Follow these steps to set up and run the Liny project: Open the `.env` file and fill in the required fields. You can leave the SMTP fields empty if not needed. -3. If you're self-hosting, set `SELFHOSTED` to `true` in the `.env` file to block other users from creating projects. +3. If you're self-hosting, set `SELFHOSTED` to `true` in the `.env` file to block other users from creating projects in your instance. (Default is `true`) 4. Install dependencies using your preferred package manager. For pnpm: @@ -29,9 +29,11 @@ Follow these steps to set up and run the Liny project: 5. Set up the database: - ```bash - npx prisma db push - ``` +> If you're using Supabase, Please refer to the [Supabase Setup Guide](./use-supabase.md) and come back. + +```bash +npx prisma db push +``` 6. Build the project: diff --git a/docs/use-supabase.md b/docs/use-supabase.md new file mode 100644 index 0000000..0fce688 --- /dev/null +++ b/docs/use-supabase.md @@ -0,0 +1,24 @@ +## Guide to using Supabase as your database + +### Setting up Supabase + +1. Go to [Supabase](https://supabase.com/) and sign up for an account. +2. If you're prompted to choose an organization, select the default organization. +3. Now, Click on the "New Project" button. +4. Enter the project details: + - Project Name: "Liny" + - Database Password: SOMETHINGSECURE (replace with a secure password) + - Region: "us-east-1" (or closest to you) +5. Click on the "Create Project" button. +6. Once the project is created, you will be redirected to the project dashboard. +7. Click on the green color "Connect" button. +8. A modal will appear. Click on the "Connection String" tab. +9. Copy the connection string. +10. Open the `.env` file and paste the connection string into the `DATABASE_URL` variable. +11. Replace the port `6543` with `5432`. +12. Password is the one you chose in step 4. +13. Now run `npx prisma db push` to create the tables. + +--- + +That's it! You've successfully set up Supabase as your database.