Skip to content

Commit

Permalink
chore: update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@riipandi
riipandi committed Sep 4, 2024
1 parent dd881b5 commit 90019c0
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 82 deletions.
84 changes: 58 additions & 26 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,56 @@ This way we can guide you through the process and give feedback.

## 🏁 Quick Start

### Prerequisites
You will need `Node.js >=20.11.1`, `pnpm >=9.9.0` and `Docker >= 20.10` installed on your machine.

You will need `Node.js >=18.17.1` and `Docker >= 20.10` installed on your machine.
Optionally, you can use [Docker Slim][docker-slim] to reduce the container image size.

### Up and Running

1. Install the required toolchain & SDK: [Node.js][install-nodejs] and [Docker][docker].
2. Create `.env` file or copy from `.env.example`, then configure required variables.
3. Generate application secret key, use [Generate Secret](#generate-secret) command.
4. Install required dependencies: `pnpm install`
5. Run project in development mode: `pnpm dev`
1. Install the required toolchain & SDK: [Node.js][nodejs], [pnpm][pnpm], and [Docker][docker].
2. Install required project dependencies: `pnpm install`
3. Create `.env` file or copy from `.env.example`, then configure required variables.
4. Generate application secret key: `pnpm generate:key`
5. Start the database server and local SMTP server: `pnpm pre-dev`
6. Prepare database migrations: `pnpm db:generate`
7. Run project in development mode: `pnpm dev`

Type `cargo --help` on your terminal and see the available `cargo` commands.
If you don't have OpenSSL installed, an alternative option for generating a secret key
is to use [1password][1password] to create a random secret.

### Generate Secret
Application will run at <http://localhost:3000>

You need to set the `secret key` with a random string. To generate a secret key,
use the following command:
For detailed explanation on how things work, check out [Remix documentation][remix-docs].

### OAuth Configuration

Callback: `http://localhost:3000/auth/<PROVIDER>/callback`

### Webhooks

In order to receive webhooks (_i.e. notifications, payment integrations, etc_), you will need
to expose the local port to the internet. To expose a local port to the internet, you can use
service like [Tailscale Funnel][tailscale], [Expose by Beyond Code][expose-dev], or [ngrok][ngrok].

In this case we will use Tailscale Funnel. By default, no alias for `tailscale` is set up.
If you plan on frequently accessing the Tailscale CLI, you can add an alias to your `.bashrc`
or `.zshrc` to make it easier.

```sh
alias tailscale="/Applications/Tailscale.app/Contents/MacOS/Tailscale"
```

```sh
tailscale funnel --bg=false http://localhost:3000
tailscale funnel status
```

Reference: https://www.twilio.com/blog/expose-localhost-to-internet-with-tunnel

### E2E Testing

```sh
openssl rand -base64 500 | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
pnpm e2e-test:ui
```

## 🔰 Database Migration
Expand All @@ -48,15 +77,20 @@ docker-compose down --remove-orphans --volumes
### Build Container

```sh
docker build -f Dockerfile . -t remix-start
pnpm docker:build
```

docker image list | grep remix-start
### List Docker Images

```sh
pnpm docker:images
```

### Testing Container

```sh
docker run --rm -it -p 3000:3000 --env-file .env.docker --name remix-start remix-start
# Run API Docker container in foreground
docker run --rm -it -p 3000:3000 --name remix-start --env-file .env remix-start
```

### Push Images
Expand All @@ -77,15 +111,13 @@ docker push ghcr.io/riipandi/remix-start:latest

Read [Deployment Guide](./DEPLOY.md) for detailed documentation.

## 🪪 Licensing

This project is licensed under the [MIT License][mit-license], which allows for the
freedom to use, modify, and distribute the software while retaining the requirement
that the original copyright notice and disclaimer are included in all copies or
substantial portions of the software. Contributions are subject to the same license
terms, and contributors agree to transfer ownership of their contributions to the
project maintainers.

<!-- link reference definition -->
[1password]: https://1password.com/password-generator
[docker-slim]: https://github.com/slimtoolkit/slim
[docker]: https://docs.docker.com/engine/install
[install-nodejs]: https://nodejs.org/en/download
[mit-license]: https://choosealicense.com/licenses/mit/
[expose-dev]: https://expose.dev/
[ngrok]: https://ngrok.com/
[nodejs]: https://nodejs.org/en/download/
[pnpm]: https://pnpm.io/installation
[remix-docs]: https://remix.run/docs
[tailscale]: https://tailscale.com/kb/1223/funnel
62 changes: 6 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,6 @@

Minimal containerized Remix Stack with Tailwind CSS.

```sh
pnpm create remix --template riipandi/remix-start app_name
```

Learn more about [Remix Stacks][remix-stacks].

---
Expand All @@ -27,54 +23,11 @@ Learn more about [Remix Stacks][remix-stacks].

## 🏁 Quickstart

At least you will need `Node.js >=20.11.1` and `Docker >= 20.10` for building the container.

### Generate Secret Key

Before you continue, you need to create `.env` file (you can duplicate `.env.example`) and
fill the `application secret key` with some random string. To generate a secret key, use
the following command:

```sh
openssl rand -base64 500 | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
```

If you don't have openssl installed, you can also use [1password][1password]
to generate a random secret.

### Up and running

```sh
pnpm install # install the dependencies
pnpm dev # serve with hot reload

pnpm build # build for production
pnpm start # launch generated build
```

This starts your app in development mode, rebuilding assets on file changes.

### E2E Testing

```sh
pnpm e2e-test:ui
```

## 🐳 Build Container

```sh
pnpm docker:build
pnpm docker:images
```

```sh
# Run API Docker container in foreground
docker run --rm -it -p 3000:3000 --name remix-start --env-file .env remix-start
pnpm create remix --template riipandi/remix-start app_name
```

## 🚀 Deployment

[Read the guide](./DEPLOY.md) to learn how to deploy this project.
Read the [CONTRIBUTING.md](./CONTRIBUTING.md) to get started with the project.

## 🧑🏻‍💻 Development

Expand All @@ -86,10 +39,8 @@ really great in-editor experience with type checking and auto-complete.

## 👷‍♂️ Contributions

Contributions are welcome! Please open a pull requests for your changes and tickets in case
you would like to discuss something or have a question.

Read [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed documentation.
Contributions are welcome! Please open a pull requests for your changes and tickets
in case you would like to discuss something or have a question.

## 🙏 Thanks to...

Expand All @@ -111,17 +62,16 @@ See the [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) file

<sub>🤫 Psst! If you like my work you can support me via [GitHub sponsors](https://github.com/sponsors/riipandi).</sub>

[![Made by](https://badgen.net/badge/icon/Made%20by%20Aris%20Ripandi?icon=bitcoin-lightning&label&color=black&labelColor=black)][riipandi-x]

<!-- link reference definition -->
[1password]: https://1password.com/password-generator
[biome]: https://biomejs.dev
[clsx]: https://www.npmjs.com/package/clsx
[docker]: https://docs.docker.com/engine/install
[fly-io]: https://fly.io/docs/reference/configuration/#services-http_checks
[license-apache]: https://choosealicense.com/licenses/apache-2.0/
[license-mit]: https://choosealicense.com/licenses/mit/
[nodejs]: https://nodejs.org/en/download/
[playwright]: https://playwright.dev
[pnpm]: https://pnpm.io/installation
[remix-stacks]: https://remix.run/docs/en/main/guides/templates#stacks
[riipandi-x]: https://x.com/intent/follow?screen_name=riipandi
[tailwind-merge]: https://www.npmjs.com/package/tailwind-merge
Expand Down

0 comments on commit 90019c0

Please sign in to comment.