sharedinbox/DEVELOPMENT.md

Development Environment Setup

This document explains how to set up a development environment for SharedInbox.

⚠️ Security Recommendation: Use a Dedicated Linux User

For enhanced security, especially when working with autonomous coding agents (like Gemini CLI in YOLO mode), we strongly recommend using a dedicated Linux user for this project. This isolates the project environment and prevents any potential accidental damage to your main system.

1. Create a Dedicated User

Set the user name variable (default is si for SharedInbox):

export DEV_USER=si

Create the user and add them to the sudo group:

sudo adduser --disabled-password newuser $DEV_USER

Set up SSH public key login (replace with your actual public key):

sudo mkdir -p /home/$DEV_USER/.ssh
sudo chmod 700 /home/$DEV_USER/.ssh
echo "ssh-ed25519 AAAA... your-key-comment" | sudo tee /home/$DEV_USER/.ssh/authorized_keys
sudo chmod 600 /home/$DEV_USER/.ssh/authorized_keys
sudo chown -R $DEV_USER:$DEV_USER /home/$DEV_USER/.ssh

2. Switch to the Dedicated User

ssh $DEV_USER@localhost

Create ssh-keypair

ssh-keygen

3. Clone the Repository

Clone the project into your new user's home directory:

git clone ssh://git@codeberg.org/guettli/sharedinbox.git

# Move git directory into $HOME
# This user only works on the git repo. Avoid "cd sharedinbox" after each login...
mv sharedinbox/* .
mv sharedinbox/.??* .
rmdir sharedinbox/

3b. Configure Git Identity

The new user needs a Git identity for commits and some scripts:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

4. Install System Dependencies

This project uses Nix with flakes to manage its toolchain (Flutter, Dart, Stalwart, etc.).

mkdir -p .config/nix

echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

nix profile add nixpkgs#direnv

nix profile add nixpkgs#nix-direnv

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

.config/direnv/direnv.toml

[global] hide_env_diff = true #log_filter = "^$"

[whitelist] prefix = [ "/home/DEV_USER-CHANGE_THAT" ]

    ### 4b. Additional Permissions (GUI & Android)

    1.  **GUI Access**: To run the Linux app (`task run`) from the `si` user, you must allow it to access your X server. Run this **from your main user terminal**:
        ```bash
        xhost +local:$DEV_USER
        ```

    2.  **Android Emulator (KVM)**: If you plan to use the Android emulator, add the user to the `kvm` group:
        ```bash
        sudo usermod -aG kvm $DEV_USER
        ```

    ### 5. Project Setup

    Once you are in the project directory and have the dependencies installed:

    1.  **Initialize Environment**:
        ```bash
        cp .env.example .env
        ```

    2.  **Allow direnv**:
        ```bash
        direnv allow
        ```
        *This will trigger Nix to download and set up the environment (Flutter, Android SDK, etc.). It might take some time on the first run.*

    3.  **Install Flutter (via FVM)**:
        Nix provides FVM, which manages the pinned Flutter version.
        ```bash
        fvm install
        ```

    4.  **Initial Setup**:
        Run the comprehensive setup command which handles `pub get`, code generation, and git hooks:
        ```bash
        task setup
        ```

### 6. Verify the Setup

Run the full check suite to ensure everything is working correctly:

```bash
task check

7. Running the App

To run the app on your Linux desktop:

task run

---

Working with VS Code

To maintain isolation, it is recommended to run VS Code "remotely" on the dedicated development user.

Preferred Method: VS Code Remote - SSH

The most robust way to work with a separate user is using the VS Code Remote - SSH extension. This allows you to run the VS Code Server as the si user while using your main user's GUI.

1. Install the Extension: Install "Remote - SSH" from the VS Code Marketplace.
2. Enable SSH for the Dev User: From your main user, copy your SSH public key to the dev user:

   # As your main user:
   sudo mkdir -p /home/$DEV_USER/.ssh
   sudo cp ~/.ssh/id_rsa.pub /home/$DEV_USER/.ssh/authorized_keys
   sudo chown -R $DEV_USER:$DEV_USER /home/$DEV_USER/.ssh
   sudo chmod 700 /home/$DEV_USER/.ssh
   sudo chmod 600 /home/$DEV_USER/.ssh/authorized_keys
   

3. Connect: In VS Code, open the Command Palette (Ctrl+Shift+P) and select Remote-SSH: Connect to Host.... Enter: si@localhost (or $DEV_USER@localhost).
4. Install Extensions in the Remote: Once connected, you will need to install the following extensions on the remote user:
   • Dart / Flutter
   • direnv: (by mkhl) Highly recommended to automatically load the Nix environment inside VS Code.
   • Nix IDE: For syntax highlighting.

Why SSH?

Using SSH to localhost is preferred over complex X11/Wayland permission hacks. It provides a clean boundary for the VS Code process and any integrated terminal or coding agents, ensuring they cannot access your personal files in /home/$YOUR_USER.

Note on Security: While these instructions add the user to the sudo group for convenience during setup, you can remove it later with sudo gpasswd -d $DEV_USER sudo to further restrict the user and any coding agents.

---

Daily Workflow

Refer to the README.md for common development tasks and commands.