From 2d8ffae74bb0e92ac5f9be88ea4f169edb100963 Mon Sep 17 00:00:00 2001 From: mngshm Date: Thu, 17 Apr 2025 14:11:54 +0530 Subject: [PATCH] un-index web-app.md, surface new doc `/guides/from-source` --- docs/docs/.vitepress/sidebar.ts | 4 +- docs/docs/self-hosting/guides/from-source.md | 250 +++++++++++++++++++ 2 files changed, 252 insertions(+), 2 deletions(-) create mode 100644 docs/docs/self-hosting/guides/from-source.md diff --git a/docs/docs/.vitepress/sidebar.ts b/docs/docs/.vitepress/sidebar.ts index 40123e4795..032bb8d6e6 100644 --- a/docs/docs/.vitepress/sidebar.ts +++ b/docs/docs/.vitepress/sidebar.ts @@ -248,8 +248,8 @@ export const sidebar = [ link: "/self-hosting/guides/custom-server/", }, { - text: "Hosting the web app", - link: "/self-hosting/guides/web-app", + text: "Hosting Ente from source", + link: "/self-hosting/guides/from-source", }, { text: "Configuring S3", diff --git a/docs/docs/self-hosting/guides/from-source.md b/docs/docs/self-hosting/guides/from-source.md new file mode 100644 index 0000000000..6e7acd4063 --- /dev/null +++ b/docs/docs/self-hosting/guides/from-source.md @@ -0,0 +1,250 @@ +--- +title: Ente from Source +description: Getting started self hosting Ente Photos and/or Ente Auth +--- + + +## Ente from Source + +#### Installing Docker + +Refer to +[How to install Docker from the APT repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) +for detailed instructions. + +#### Start the server + +```sh +git clone https://github.com/ente-io/ente +cd ente/server +docker compose up --build +``` + +> [!TIP] +> +> You can also use a pre-built Docker image from `ghcr.io/ente-io/server` +> ([More info](https://github.com/ente-io/ente/blob/main/server/docs/docker.md)) + +Install the necessary dependencies for running the web client + +```sh +# installing npm and yarn + +sudo apt update +sudo apt install nodejs npm +sudo npm install -g yarn // to install yarn globally +``` + +Then in a separate terminal, you can run (e.g) the web client + +```sh +cd ente/web +git submodule update --init --recursive +yarn install +NEXT_PUBLIC_ENTE_ENDPOINT=http://localhost:8080 yarn dev +``` + +That's about it. If you open http://localhost:3000, you will be able to create +an account on a Ente Photos web app running on your machine, and this web app +will be connecting to the server running on your local machine at +`localhost:8080`. + +For the mobile apps, you don't even need to build, and can install normal Ente +apps and configure them to use your +[custom self-hosted server](guides/custom-server/). + +> If you want to build the mobile apps from source, see the instructions +> [here](guides/mobile-build). + + + +> [!WARNING] NOTE +> This page covers documentation around self-hosting the web app manually. If you +> want to deploy Ente hassle free, please use the [one line](https://ente.io/blog/self-hosting-quickstart/) +> command to setup Ente. This guide might be deprecated in the near future. + +# Web app + +The getting started instructions mention using `yarn dev` (which is an alias of +`yarn dev:photos`) to serve your web app. + +>[!IMPORTANT] +> Please note that Ente's Web App supports the Yarn version 1.22.xx or 1.22.22 specifically. +> Make sure to install the right version or modify your yarn installation to meet the requirements. +> The user might end up into unknown version and dependency related errors if yarn +> is on different version. + +```sh +cd ente/web +git submodule update --init --recursive +yarn install +NEXT_PUBLIC_ENTE_ENDPOINT=http://localhost:8080 yarn dev:photos +``` + +This is fine for trying the web app and verifying that your self-hosted server +is working as expected etc. But if you would like to use the web app for a +longer term, then it is recommended to follow the Docker approach. + +## With Docker/Docker Compose (Recommended) + +> [!IMPORTANT] +> +> Recurring changes might be made by the team or from community if more +> improvements can be made so that we are able to build a full-fledged docker +> image. + +```dockerfile +FROM node:20-bookworm-slim as builder + +WORKDIR ./ente + +COPY . . +COPY apps/ . + +# Will help default to yarn versoin 1.22.22 +RUN corepack enable + +# Endpoint for Ente Server +ENV NEXT_PUBLIC_ENTE_ENDPOINT=https://your-ente-endpoint.com +ENV NEXT_PUBLIC_ENTE_ALBUMS_ENDPOINT=https://your-albums-endpoint.com + +RUN yarn cache clean +RUN yarn install --network-timeout 1000000000 +RUN yarn build:photos && yarn build:accounts && yarn build:auth && yarn build:cast + +FROM node:20-bookworm-slim + +WORKDIR /app + +COPY --from=builder /ente/apps/photos/out /app/photos +COPY --from=builder /ente/apps/accounts/out /app/accounts +COPY --from=builder /ente/apps/auth/out /app/auth +COPY --from=builder /ente/apps/cast/out /app/cast + +RUN npm install -g serve + +ENV PHOTOS=3000 +EXPOSE ${PHOTOS} + +ENV ACCOUNTS=3001 +EXPOSE ${ACCOUNTS} + +ENV AUTH=3002 +EXPOSE ${AUTH} + +ENV CAST=3003 +EXPOSE ${CAST} + +# The albums app does not have navigable pages on it, but the +# port will be exposed in-order to self up the albums endpoint +# `apps.public-albums` in museum.yaml configuration file. +ENV ALBUMS=3004 +EXPOSE ${ALBUMS} + +CMD ["sh", "-c", "serve /app/photos -l tcp://0.0.0.0:${PHOTOS} & serve /app/accounts -l tcp://0.0.0.0:${ACCOUNTS} & serve /app/auth -l tcp://0.0.0.0:${AUTH} & serve /app/cast -l tcp://0.0.0.0:${CAST}"] +``` + +The above is a multi-stage Dockerfile which creates a production ready static +output of the 4 apps (Photos, Accounts, Auth and Cast) and serves the static +content with Caddy. + +Looking at 2 different node base-images doing different tasks in the same +Dockerfile would not make sense, but the Dockerfile is divided into two just to +improve the build efficiency as building this Dockerfile will arguably take more +time. + +Lets build a Docker image from the above Dockerfile. Copy and paste the above +Dockerfile contents in the root of your web directory which is inside +`ente/web`. Execute the below command to create an image from this Dockerfile. + +```sh +# Build the image +docker build -t : --no-cache --progress plain . +``` + +You can always edit the Dockerfile and remove the steps for apps which you do +not intend to install on your system (like auth or cast) and opt out of those. + +Regarding Albums App, please take a note that they are not web pages with +navigable pages, if accessed on the web-browser they will simply redirect to +ente.web.io. + +## compose.yaml + +Moving ahead, we need to paste the below contents into the compose.yaml inside +`ente/server/compose.yaml` under the services section. + +```yaml +ente-web: + image: # name of the image you used while building + ports: + - 3000:3000 + - 3001:3001 + - 3002:3002 + - 3003:3003 + - 3004:3004 + environment: + - NODE_ENV=development + restart: always +``` + +Now, we're good to go. All we are left to do now is start the containers. + +```sh +docker compose up -d # --build + +# Accessing the logs +docker compose logs +``` + +## Configure App Endpoints + +> [!NOTE] +> Previously, this was dependent on the env variables `NEXT_ENTE_PUBLIC_ACCOUNTS_ENDPOINT` +> and etc. Please check the below documentation to update your setup configurations + +You can configure the web endpoints for the other apps including Accounts, Albums +Family and Cast in your `museum.yaml` configuration file. Checkout +[`local.yaml`](https://github.com/ente-io/ente/blob/543411254b2bb55bd00a0e515dcafa12d12d3b35/server/configurations/local.yaml#L76-L89) +to configure the endpoints. Make sure to setup up your DNS Records accordingly to the +similar URL's you set up in `museum.yaml`. + +Next part is to configure the web server. + +# Web server configuration + +The last step ahead is configuring reverse_proxy for the ports on which the apps +are being served (you will have to make changes, if you have cusotmized the +ports). The web server of choice in this guide is +[Caddy](https://caddyserver.com) because with caddy you don't have to manually +configure/setup SSL ceritifcates as caddy will take care of that. + +```sh +photos.yourdomain.com { + reverse_proxy http://localhost:3001 + # for logging + log { + level error + } +} + +auth.yourdomain.com { + reverse_proxy http://localhost:3002 +} +# and so on ... +``` + +Next, start the caddy server :). + +```sh +# If caddy service is not enabled +sudo systemctl enable caddy + +sudo systemctl daemon-reload +sudo systemctl start caddy +``` + +## Contributing + +Please start a discussion on the Github Repo if you have any suggestions for the +Dockerfile, You can also share your setups on Github Discussions.