From 2216c2c746243c7a1b87af578b69e53fc4d5bd43 Mon Sep 17 00:00:00 2001 From: Manav Rathi Date: Fri, 21 Mar 2025 11:41:04 +0530 Subject: [PATCH] Outline new approach and move doc --- docs/docs/self-hosting/faq/otp.md | 5 ++ server/docs/quickstart.md | 119 ++++++++++++++++++++++++++++++ server/quickstart/README.md | 114 ---------------------------- 3 files changed, 124 insertions(+), 114 deletions(-) create mode 100644 server/docs/quickstart.md delete mode 100644 server/quickstart/README.md diff --git a/docs/docs/self-hosting/faq/otp.md b/docs/docs/self-hosting/faq/otp.md index 18116905b2..5a9b8d0f2d 100644 --- a/docs/docs/self-hosting/faq/otp.md +++ b/docs/docs/self-hosting/faq/otp.md @@ -12,6 +12,11 @@ verification code by: - Reading it from the DB (otts table) +> [!TIP] +> +> You can also configure your instance to send out emails so that you can get +> your verification code via emails by using the `smtp` section in the config. + You can also set pre-defined hardcoded OTTs for certain users when running locally by creating a `museum.yaml` and adding the `internal.hardcoded-ott` configuration setting to it. See diff --git a/server/docs/quickstart.md b/server/docs/quickstart.md new file mode 100644 index 0000000000..d8a7534fb5 --- /dev/null +++ b/server/docs/quickstart.md @@ -0,0 +1,119 @@ +# quickstart.sh + +The quickstart.sh script creates a Docker compose file that does not require +cloning the repository, and uses pre-built images instead. It is meant to +provide an easy way for people to get started with self hosting Ente without +needing to build museum or the web app from source. + +The easiest way to run the script is to copy paste the following command into +your terminal: + +```sh +sh -c "$(curl -fsSL https://raw.githubusercontent.com/ente-io/ente/main/server/quickstart.sh)" +``` + +After the Docker compose cluster starts, you can open the Ente web app at +http://localhost:3000. + +> [!TIP] +> +> The verification code when you try to create an account can be seen in the +> logs (See [self hosting +> docs](https://help.ente.io/self-hosting/faq/otp#verification-code) for more +> ways to get it) + +## Details + +The only requirement the script has is for a recent-ish version of Docker. + +The script first creates a directory named `my-ente` and changes to it. + +> [!TIP] +> +> "Ente" (pronounced _en-tay_) means "mine" in Malayalam, our Founder's mother +> tongue (the product literally thus means "My Photos"), so our quickstart +> directory name `my-ente` means "my-my". + +Then it creates a Docker compose file (`compose.yaml`) from a template, and a +`museum.yaml` with fresh autogenerated credentials. + +Finally, it start the Docker compose cluster running + +- Ente's own server (museum) +- Ente's web app +- Postgres (DB) +- Minio (S3 storage) + +For each of these, it'll use the latest published Docker image. + +You can do a quick smoke test by pinging the API: + +```sh +curl localhost:8080/ping +``` + +Or directly start using the web app by opening http://localhost:3000 in your +browser. + +The first time around, the cluster will keep running as long as the +`quickstart.sh` script is running (you can stop it by using `Ctrl-C`). + +Subsequently, whenever you want to start the cluster, you can go back to the +same directory and run `docker compose up` again. + +```sh +cd /path/to/my-ente # Or whichever directory you created +docker compose up +``` + +If you want to keep it running in the background, you can pass the `-d` flag to +the `docker compose up` command: + +```sh +cd /path/to/my-ente +docker compose up -d +``` + +And then later, to stop the cluster, you can: + +```sh +cd /path/to/my-ente +docker compose down +``` + +Apart from this `my-ente` directory, the script does not install anything else +on your system. All persistent data is saved in volumes managed by Docker. + +> [!CAUTION] +> +> You can clear these volumes by +> +> ```sh +> cd /path/to/my-ente +> docker compose down --volumes +> ``` +> +> Beware that this will permanently remove these volumes, including any photos +> you added to your self hosted instance. + +### Caveat + +This sample setup is only intended to make it easy for people to get started. If +you're intending to use your self hosted instance for serious purposes, we +strongly recommend understanding all the moving parts, and consider if you +should use an external S3 (/ DB) instead of the quickstart samples. + +> [!IMPORTANT] +> +> Keep a plaintext backup of your photos until you are sure of what you are +> doing and have a [backup +> strategy](https://help.ente.io/self-hosting/faq/backup) worked out. + +## Next steps + +See **[help.ente.io/self-hosting](https://help.ente.io/self-hosting)** for +guides on connecting to your self hosted instance [using your mobile +app](https://help.ente.io/self-hosting/guides/custom-server/), modifying your +setup to allow +[uploading](https://help.ente.io/self-hosting/guides/configuring-s3) from your +mobile app, and other customizations. diff --git a/server/quickstart/README.md b/server/quickstart/README.md deleted file mode 100644 index 2437a0976b..0000000000 --- a/server/quickstart/README.md +++ /dev/null @@ -1,114 +0,0 @@ -A variant docker compose file that does not require cloning the repository, and -uses pre-built images instead. - -## Quickstart - -Copy paste the following command into your terminal - -```sh -sh -c "$(curl -fsSL https://raw.githubusercontent.com/ente-io/ente/main/server/quickstart.sh)" -``` - -Alternatively, you can run the following four steps manually (that's all the -command above does for you): - -1. Create a directory on your system and switch to it. You can name it - anything, and it can be at any place on your machine. In particular, you - don't need to clone this repository. - - ```sh - mkdir my-ente && cd my-ente - ``` - -> [!TIP] -> -> "Ente" (pronounced _en-tay_) means "mine" in Malayalam, our Founder's mother -> tongue (the product literally thus means "My Photos"), so our example -> directory name `my-ente` would mean to "my-my". - -2. Download the sample quickstart Docker compose file. - - ```sh - curl -fsSOL https://raw.githubusercontent.com/ente-io/ente/main/server/quickstart/compose.yaml - ``` - -> [!CAUTION] -> -> The `quickstart.sh` also updates the default passwords and keys in -> `compose.yaml` with new autogenerated ones. If you're doing these steps -> manually, remember to update the credentials too. - -3. Create an empty `museum.yaml` (you can use it later to put extra config if - needed). - - ```sh - touch museum.yaml - ``` - -4. Start your self hosted instance. - - ```sh - docker compose up - ``` - -That's it. You can now open http://localhost:3000 in your browser to use Ente's -web app. - -## Details - -The quickstart steps above created a Docker compose cluster containing: - -- Ente's own server, museum -- Ente's web app -- Postgres (DB) -- Minio (S3 storage) - -For each of these, it'll use the latest published Docker image. - -You can do a quick smoke test by pinging the API: - -```sh -curl localhost:8080/ping -``` - -And start using the web app by opening http://localhost:3000 in your browser. - -The cluster will keep running as long as the `docker compose up` command (or the -`quickstart.sh` script you curl-ed) is running. If you want to keep it running -in the background, you can instead: - -```sh -cd /path/to/my-ente # Or whichever directory you created -docker compose up -d -``` - -And then later, to stop the cluster, you can: - -```sh -cd /path/to/my-ente -docker compose down -``` - -### Caveat - -This sample setup is only intended to make it easy for people to get started. If -you're intending to use your self hosted instance for serious purposes, we -strongly recommend understanding all the moving parts, and consider if you -should use an external S3 (/ DB) instead of the quickstart samples. - -> [!IMPORTANT] -> -> Keep a plaintext backup of your photos until you are sure of what you are -> doing and have a [backup -> strategy](https://help.ente.io/self-hosting/faq/backup) worked out. - -## Next steps - -* Get a login [verification - code](https://help.ente.io/self-hosting/faq/otp#verification-code). - -* Connect to your self hosted instance [from your mobile - app](https://help.ente.io/self-hosting/guides/custom-server/). - -* Modify your setup to allow [uploading from your mobile - app](https://help.ente.io/self-hosting/guides/configuring-s3).