diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 33e551f..a2167f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 -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//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 @@ -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 @@ -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. - + +[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 diff --git a/README.md b/README.md index 2fccdb1..f11fec5 100644 --- a/README.md +++ b/README.md @@ -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]. --- @@ -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 @@ -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... @@ -111,17 +62,16 @@ See the [LICENSE-APACHE](./LICENSE-APACHE) and [LICENSE-MIT](./LICENSE-MIT) file 🤫 Psst! If you like my work you can support me via [GitHub sponsors](https://github.com/sponsors/riipandi). +[![Made by](https://badgen.net/badge/icon/Made%20by%20Aris%20Ripandi?icon=bitcoin-lightning&label&color=black&labelColor=black)][riipandi-x] + -[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