Skip to content

Commit

Permalink
Proxy and redirects (and more docs). (#202)
Browse files Browse the repository at this point in the history 
* Docs: Proxy and redirects / Draft and releases / Installing app.
  • Loading branch information
@matheusgr
matheusgr authored Nov 1, 2023
1 parent 6878ed3 commit 0a6925b
Show file tree
Hide file tree
Showing 7 changed files with 199 additions and 104 deletions.
32 changes: 13 additions & 19 deletions docs/getting-started/installing-an-app/en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,34 +5,28 @@ since: 1.33.2

# Prerequisites

Before you begin, make sure you have a deco site ready, and the desired App should be available in the Apps directory. If you're unsure how to achieve this, refer to the [making an app installable tutorial](/docs/en/developing/making-an-app-installable).
Before you begin, make sure you have a ready Deco site, and the desired App should be available in the Apps directory. If you're unsure how to do this, refer to the [tutorial on making an app installable](/docs/en/developing/making-an-app-installable).

## Step 1: Log in to deco Admin
# Apps

Start by logging in to your deco Admin account. Visit [https://deco.cx/admin](https://deco.cx/admin) and enter your credentials.
An `App` allows you to add new functionalities to your site in a straightforward manner.

## Step 2: Choose Your Target Site
# Installing the App

After logging in, select the specific site where you want to install the App. You'll be directed to the site's home.
1. **Access the Deco Admin:** Start by logging into your Deco Admin account. Visit [https://admin.deco.cx](https://admin.deco.cx) and enter your credentials.

## Step 3: Access the "Apps" Section
2. **Choose the Target Site:** After logging in, select the specific site where you want to install the App. You will be directed to the site's homepage.

In the site's home, navigate to the "Apps" section. This section is where you'll find all the Apps available for installation.
3. **Access the "Apps" Section:** On the site's homepage, navigate to the "Apps" section. This is where you will find all the Apps available for installation. Select to view all "available Apps".

## Step 4: Add the App Block
![Apps Section](https://github.com/deco-cx/apps/assets/882438/e2533612-6828-4fb6-9959-96f000ca3537)

Inside the "Apps" section, create a new App block. Give it a name; it's commonly used to specify the version, such as `site@v0` and publish it.
4. **Add an App Block:** Click on "Add" to install an App. This starts the process of creating a block. Configure the block and click on "Create" (give it a name; it's common to use the version, like `site@v0`).

## Step 5: Configure the App
5. **Explore Installed Blocks:** Once installed, you will have access to all the blocks and components that an App includes. These blocks can be integrated into your Deco site to provide additional functionality.

With the App block created, you'll also be prompted to fulfill any required configurations or parameters.
Congratulations! You have successfully installed an App using the Deco Admin. Explore the new capabilities and features that an installed App brings to your Deco site. Feel free to further customize the App or explore other available Apps to expand the functionality of your Deco project. Enjoy managing and enhancing your Deco site! 🚀

## Step 6: Save and Publish
> You can always change the App settings by clicking on the created block.
After configuring the App block, click "Save and Publish" to apply the changes and install the App on your site.

## Step 7: Explore the Installed Blocks

Once the App is installed, you'll have access to all the blocks and components it includes. These blocks can be integrated into your deco site to provide additional functionalities.

Congratulations! You've successfully installed an App using deco Admin. Explore the newfound capabilities and features that the installed App brings to your deco site. Feel free to customize the App further or explore other available Apps to expand your deco project's functionalities. Enjoy managing and enhancing your deco site! 🚀
![Changing App Settings](https://github.com/deco-cx/apps/assets/882438/5cf7fe48-89b1-47cd-be82-2f7ff601e640)
30 changes: 12 additions & 18 deletions docs/getting-started/installing-an-app/pt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,26 @@ desde: 1.33.2

Antes de começar, certifique-se de ter um site deco pronto, e a App desejado deve estar disponível no diretório Apps. Se você não tem certeza de como fazer isso, consulte o [tutorial de tornar uma app instalável](/docs/en/developing/making-an-app-installable).

## Passo 1: Acesse o deco Admin
# Apps

Comece fazendo login na sua conta do deco Admin. Visite [https://deco.cx/admin](https://deco.cx/admin) e insira suas credenciais.
Uma `App` permite adicionar novas funcionalidades no seu site de maneira bem direta.

## Passo 2: Escolha o Site de Destino
# Instalando a app

Após fazer login, selecione o site específico onde deseja instalar o App. Você será direcionado para a página inicial do site.
1. **Acesse o deco Admin:** Comece fazendo login na sua conta do deco Admin. Visite [https://admin.deco.cx](https://admin.deco.cx) e insira suas credenciais.

## Passo 3: Acesse a Seção "Apps"
2. **Escolha o Site de Destino:** Após fazer login, selecione o site específico onde deseja instalar o App. Você será direcionado para a página inicial do site.

Na página inicial do site, navegue até a seção "Apps". Esta é a seção onde você encontrará todos os Apps disponíveis para instalação.
3. **Acesse a Seção "Apps":** Na página inicial do site, navegue até a seção "Apps". Esta é a seção onde você encontrará todos os Apps disponíveis para instalação. Selecione para ver todos os Apps disponíveis.

## Passo 4: Adicione um Bloco da app
![Seção de Apps](https://github.com/deco-cx/apps/assets/882438/e2533612-6828-4fb6-9959-96f000ca3537)

Dentro da seção "Apps", crie um novo bloco da App. Dê a ele um nome; é comum usar a versão, como `site@v0`, e publique-o.
4. **Adicione um Bloco da app:** Clique em adicionar App. Isto inicia o processo de criar um bloco. Configure o bloco e clique em criar. (dê a ele um nome; é comum usar a versão, como `site@v0`).

## Passo 5: Configure a App
5. **Explore os Blocos Instalados:** Depois de instalado, você terá acesso a todos os blocos e componentes que um App inclui. Esses blocos podem ser integrados ao seu site deco para fornecer funcionalidades adicionais.

Com um bloco da app criado, você também será solicitado a preencher quaisquer configurações ou parâmetros necessários.

## Passo 6: Salve e Publique

Após configurar o bloco da app, clique em "Salvar e Publicar" para aplicar as alterações e instalar um App no seu site.

## Passo 7: Explore os Blocos Instalados
Parabéns! Você instalou com sucesso um App usando o deco Admin. Explore as novas capacidades e recursos que um App instalado traz para o seu site deco. Sinta-se à vontade para personalizar o App ainda mais ou explorar outros Apps disponíveis para expandir as funcionalidades do seu projeto deco. Aproveite para gerenciar e aprimorar o seu site deco! 🚀

Depois de instalado, você terá acesso a todos os blocos e componentes que um App inclui. Esses blocos podem ser integrados ao seu site deco para fornecer funcionalidades adicionais.
> É possível sempre alterar as configurações do Apps clicando no bloco criado.
Parabéns! Você instalou com sucesso um App usando o deco Admin. Explore as novas capacidades e recursos que um App instalado traz para o seu site deco. Sinta-se à vontade para personalizar o App ainda mais ou explorar outros Apps disponíveis para expandir as funcionalidades do seu projeto deco. Aproveite para gerenciar e aprimorar o seu site deco! 🚀
![Alterando configurações do App](https://github.com/deco-cx/apps/assets/882438/5cf7fe48-89b1-47cd-be82-2f7ff601e640)
69 changes: 48 additions & 21 deletions docs/getting-started/proxy-redirects/en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,35 +13,62 @@ By leveraging proxies and redirects, you can optimize content delivery, manage t

The overall process involves changing the site route map and attaching a proxy or a redirect depending wether your use case needs one or the other. At the end of the process we should be able to create an example route `/example-proxy` that proxies requests to deco.cx and a `/example-redirect` that redirects you to google.com homepage. Notice the difference: the former will let you in the same domain and the latter will leave your site domain.

## Step by step
## Step by Step

### Adding a Redirect
### Adding a Redirection

1. First, log in to the deco's Admin. Once you're logged in, you can access the _site_ you want to work with.
2. Open the `./routes/[...catchall].tsx` block, which is responsible for **routing** your site. You can access it by using the following link (replace $sitename with your site name): <https://deco.cx/admin/sites/$sitename/blocks/.%2Froutes%2F%5B...catchall%5D.tsx>
3. Click on `Add audiences` and a select menu will appear.<img width="1511" alt="image" src="https://github.com/deco-sites/starting/assets/5839364/18545536-5971-47d5-a6f3-22f9a740df2b">
4. Below `Create new`, select the `Audience Everyone` option.
5. A new select menu named `Routes` will appear. Under `Create new`, choose the option _deco-cx/deco/flags/audience.ts@Route[]_. Then click on the `+` button to add a new route.<img width="1508" alt="image" src="https://github.com/deco-sites/starting/assets/5839364/07e308df-6adb-4a2d-830c-eed8bca3fa06">
6. Fill in the `Path Template` field with the desired route, e.g., `/example-redirect` (ignore the `href` checkbox option for now).
7. In the `Handler` option, select `Redirect Handler` (or $live/handlers/redirect.ts).
8. In the `To` field, enter h`ttps://google.com` or the URL you want to **redirect** to.
9. Choose the type as `temporary` since this redirect may change over time. If the redirect should not change over time, you can select `permanent` (which may result in faster responses since permanent redirects are cached by the user's browser).<img width="1508" alt="image" src="https://github.com/deco-sites/starting/assets/5839364/56e3c2a9-cde2-4541-9781-58f84e27eb98">
10. Save and publish the changes.
1. First, log in to the Deco Admin. Once logged in, you can access the site you want to work with.

Now you can access <https://your-store.deco.site/example-redirect> and check if the redirect is working.
2. Go to the site's `redirects` configuration.
![Redirects in Admin](https://github.com/deco-cx/apps/assets/882438/29e9f388-2c32-4190-96e5-ac5a8001b68c)

> Please note that if you need to add a new redirect, you will need to repeat the steps from 5 onwards because the audience will already have been created.
3. Click on `Create a redirect` and configure it according to your needs.

![Create Redirect](https://github.com/deco-cx/apps/assets/882438/63a7d2a4-cc53-47eb-adca-c6cb601e7f41)

4. Fill in the `From` field with the desired route, for example, `/example-redirect`, and in the `To` field, enter `https://google.com` or the URL to which you want to **redirect**.

5. Choose the type as `temporary` since this redirection may change over time. If the redirection should not change over time, you can select `permanent` (which may result in faster responses since permanent redirects are cached by the user's browser).

6. Create the redirect to apply it.

Now you can access `https://your-site.deco.site/example-redirect` and check if the redirection is working correctly.

### Adding a Proxy

Proxies are utilized when you want to _keep the user_ within the _same website but deliver different content_. **Proxies** enable the sharing of resources under the same domain, providing a unified user experience. This can be particularly useful when you need to serve content from different sources or platforms while maintaining a consistent user interface. Proxies are commonly employed during platform migration processes, allowing you to gradually adopt deco.cx and determine whether a specific page should be proxied or served directly by deco.cx.
Proxies are used when you want to keep the user within the same site but provide different content. **Proxies** allow for sharing resources under the same domain, providing a unified user experience. This can be especially useful when you need to serve content from different sources or platforms while maintaining a consistent user interface. Proxies are commonly used during platform migration processes, allowing you to gradually adopt Deco and decide if a specific page should be proxied or served directly by Deco.

To create a proxy instead of a redirection, you can follow these steps:

1. First, log in to the Deco Admin. Once logged in, you can access the site you want to work with.

2. Open the site `App` for editing. And press to add a new `site map`.

![Add Site Map](https://github.com/deco-cx/apps/assets/882438/92427ed1-54cb-49f2-88f5-3be8c1c27b8a)

3. Select the route type as `Route`, and add this new route.

4. As the `Path template`, select the base of the route (e.g., `/example-proxy`), select the value `Proxy`, and the `URL` as the URL to be proxied (e.g., `https://deco.cx`).

5. Publish the changes.

Now, when you access the specified route (for example, `https://your-site.deco.site/example-proxy`), you will be proxied to the specified URL (in this case, `https://deco.cx`).

### Adding a Redirect File

Repeat steps 1 and 2 from the previous section. Then:

1. Upload a file named `redirect.csv` to the project's base. It should have the format as indicated below:

```
from,to,type
/example-redirect,/test,temporary
/google,https://www.google.com,permanent
```

To create a proxy instead of a redirect, you can follow the same steps mentioned above, but with a few changes:

Repeat steps 1 to 5 from the "Adding a Redirect" section.
2. Add the route of type `redirectsFromCsv.ts`.

1. In the "Handler" option, select "Proxy Handler" (or $live/handlers/proxy.ts).
2. In the "To" field, enter the exact URL that should be used as the proxy (e.g., <https://google.com>).
3. Save and publish the changes.
3. Select `redirect.csv` as the redirect file.

Now, when accessing the specified route (e.g., <https://your-store.deco.site/example-proxy>), you will be proxied to the specified URL (in this case, <https://google.com>).
4. Publish the changes.
59 changes: 43 additions & 16 deletions docs/getting-started/proxy-redirects/pt.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,30 +18,57 @@ O processo geral envolve a alteração do mapa de rotas do site e a associação
### Adicionando um Redirecionamento

1. Primeiro, faça login no Admin da deco. Uma vez logado, você pode acessar o _site_ com o qual deseja trabalhar.
2. Abra o bloco `./routes/[...catchall].tsx`, que é responsável pelo **roteamento** do seu site. Você pode acessá-lo usando o seguinte link (substitua `$sitename` pelo nome do seu site): <https://deco.cx/admin/sites/$sitename/blocks/.%2Froutes%2F%5B...catchall%5D.tsx>
3. Clique em `Adicionar Audiência` e um menu de seleção será exibido. <img width="1511" alt="image" src="https://github.com/deco-sites/starting/assets/5839364/18545536-5971-47d5-a6f3-22f9a740df2b">
4. Abaixo de `Criar novo`, selecione a opção `Audience Everyone`.
5. Um novo menu de seleção chamado `Routes` será exibido. Em `Criar novo`, escolha a opção _deco-cx/deco/flags/audience.ts@Route[]_. Em seguida, clique no botão `+` para adicionar uma nova rota. <img width="1508" alt="image" src="https://github.com/deco-sites/starting/assets/5839364/07e308df-6adb-4a2d-830c-eed8bca3fa06">
6. Preencha o campo `Path Template` com a rota desejada, por exemplo, `/example-redirect` (ignore a opção `href checkbox` por enquanto).
7. Na opção `Handler`, selecione `Redirect Handler` (ou $live/handlers/redirect.ts).
8. No campo `To`, insira `https://google.com` ou a URL para a qual deseja **redirecionar**.
9. Escolha o tipo como `temporary`, já que este redirecionamento pode mudar ao longo do tempo. Se o redirecionamento não deve mudar ao longo do tempo, você pode selecionar `permanent` (o que pode resultar em respostas mais rápidas, já que os redirecionamentos permanentes são armazenados em cache pelo navegador do usuário). <img width="1508" alt="image" src="https://github.com/deco-sites/starting/assets/5839364/56e3c2a9-cde2-4541-9781-58f84e27eb98">
10. Salve e publique as alterações.

Agora você pode acessar `https://seu-site.deco.site/example-redirect` e verificar se o redirecionamento está funcionando corretamente.
2. Entre na configuração de `redirects` do site.
![Redirects no admin](https://github.com/deco-cx/apps/assets/882438/29e9f388-2c32-4190-96e5-ac5a8001b68c)

3. Pressione `Criar um redirect` e configure de acordo com sua necessidade.

![Criar redirect](https://github.com/deco-cx/apps/assets/882438/63a7d2a4-cc53-47eb-adca-c6cb601e7f41)

4. Preencha o campo `De` com a rota desejada, por exemplo, `/example-redirect` e, em `Para`, insira `https://google.com` ou a URL para a qual deseja **redirecionar**.

5. Escolha o tipo como `temporary`, já que este redirecionamento pode mudar ao longo do tempo. Se o redirecionamento não deve mudar ao longo do tempo, você pode selecionar `permanent` (o que pode resultar em respostas mais rápidas, já que os redirecionamentos permanentes são armazenados em cache pelo navegador do usuário).

> Perceba que, se você precisa adicionar um novo redirect, você precisa repetir os passos de 5. em diante, pois a audiência já terá sido criada.
6. Crie o redirect para aplicá-lo.

Agora você pode acessar `https://seu-site.deco.site/example-redirect` e verificar se o redirecionamento está funcionando corretamente.

### Adicionando um Proxy

Proxies são utilizados quando você deseja _manter o usuário_ dentro do _mesmo site, mas fornecendo um conteúdo diferente_. Os **proxies** permitem o compartilhamento de recursos sob o mesmo domínio, proporcionando uma experiência de usuário unificada. Isso pode ser especialmente útil quando você precisa servir conteúdo de diferentes fontes ou plataformas, mantendo uma interface de usuário consistente. Os proxies são comumente usados durante processos de migração de plataforma, permitindo que você adote gradualmente o Deco e decida se uma página específica deve ser proxied ou servida diretamente pelo Deco.

Para criar um proxy em vez de um redirecionamento, você pode seguir os mesmos passos mencionados acima, com algumas alterações:
Para criar um proxy em vez de um redirecionamento, você pode seguir os seguintes passos:

1. Primeiro, faça login no Admin da deco. Uma vez logado, você pode acessar o _site_ com o qual deseja trabalhar.

2. Abra o `App` de site para edição. E pressione para adicionar um novo `site map`.

Repita os passos de 1 a 5 da seção "Adicionando um Redirecionamento".
![Adicionar site map](https://github.com/deco-cx/apps/assets/882438/92427ed1-54cb-49f2-88f5-3be8c1c27b8a)

1. Na opção "Handler", selecione "Proxy Handler" (ou `$live/handlers/proxy.ts`).
2. No campo "To", insira a URL exata que deve ser usada como proxy, por exemplo, `https://deco.cx`.
3. Salve e publique as alterações.
3. Selecione o tipo da rota como `Route`, e adicione essa nova rota.

4. Como `Path template`, selecione a base da rota (ex.: `/example-proxy`), selecione o valor `Proxy` e a `URL`, como a URL a ser proxiada (ex.: `https://deco.cx`).

5. Publique as alterações.

Agora, ao acessar a rota especificada (por exemplo, `https://seu-site.deco.site/example-proxy`), você será proxied para a URL especificada (neste caso, `https://deco.cx`).


### Adicionando um arquivo de redirects.

Repita os passos de 1 e 2 da seção anterior. Em seguida:

1. Suba um arquivo como `redirect.csv` para a base do projeto. Ele deve ter o formato indicado abaixo:

```
from,to,type
/example-redirect,/test,temporary
/google,https://www.google.com,permanent
```

2. Adicione a rota do tipo `redirectsFromCsv.ts`.

3. Selecione `redirect.csv` como arquivo de redirects.

4. Publique as alterações.
Loading

0 comments on commit 0a6925b

Please sign in to comment.