[Doc] How to Include Private Packages

.readthedocs.yml

@@ -15,4 +15,6 @@ conda:
 
 sphinx:
   builder: html
-  fail_on_warning: true
+  fail_on_warning: true
+  configuration: doc/_config.yml
+

doc/faq/faq.md

@@ -72,6 +72,79 @@ pip freeze > requirements.txt
 This will produce a new `requirements.txt` file with specific versions
 for each package, ensuring that upgrades to the dependencies don't break your app.
 
+(private-packages)=
+## Including Private Packages
+
+### UI & CLI
+To use a private packages, you'll have to do it via Docker:
+
+1. Copy your framework's base Dockerfile to project root ([Streamlit](https://github.com/ploomber/doc/blob/main/examples/streamlit/docker-based/Dockerfile), [Dash](https://github.com/ploomber/doc/blob/main/examples/dash/docker-based/Dockerfile), other framework Dockerfile can be find in our [examples](https://github.com/ploomber/doc/tree/main/examples))
+
+2. Clone your `package` to root directory (`git clone https://githib.com/org/package.git`), and **remove it from your `requirements.txt`**
+
+3. Update Dockerfile:
+```Dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# ~~~~~~~~~~~~~ NEW ~~~~~~~~~~~~~~~~
+COPY package/ package/
+RUN pip install -e package/
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+COPY requirements.txt /app/
+RUN pip install -r requirements.txt --no-cache-dir
+
+COPY . /app/
+
+CMD ["streamlit", "run", "app.py"]
+```
+
+4. Zip your project and deploy it (CLI users, simply do: `ploomber-cloud deploy`)
+
+### GitHub Workflow
+For GitHub deployments, we need to add a package download step before the deployment step. Other steps remain same as UI/CLI method.
+
+For this, you'll need to generate a personnal access token with access to the targeted repo.
+- [How to generate a Personnal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+- [How to securely give CI access to private Git repos using a **Machine User**](https://github.com/orgs/gruntwork-io/discussions/784#discussioncomment-7644683)
+
+```yaml
+jobs:
+  deploy-to-ploomber-cloud:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./server
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ploomber-cloud
+      # ~~~~~~~~~~~~~ NEW ~~~~~~~~~~~~~~~~
+      - name: Download private package
+        run: |
+          # Clone private repository
+          git clone https://${{ secrets.GH_TOKEN }}@github.com/org/package.git
+          # /!\ Remove your package from requirements.txt
+      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      - name: Deploy
+        env:
+          PLOOMBER_CLOUD_KEY: ${{ secrets.PLOOMBER_CLOUD_KEY }}
+        run: |
+          ploomber-cloud deploy --watch-incremental
+```
+
+```{note}
+Add `GH_TOKEN` secret in repository settings with permission to clone private package.
+```
+
 ## Displaying Chinese characters
 
 If you're using matplotlib and want to display Chinese characters in your plots,