dynamicalsystem.com
homelab infrastructure services
1# Ubuntu Machine Setup Automation
2
3This project automates the setup of Ubuntu machines with NAS mounting, rootless Docker installation, and persistent environment variable management.
4
5## Features
6
7- **NAS Mount Configuration**: Supports both CIFS/SMB and NFS mounting with automatic mount on boot
8- **Rootless Docker**: Installs Docker in rootless mode for enhanced security
9- **Environment Variables**: Manages environment variables from a `.env` file on the NAS
10- **Boot Persistence**: Ensures all configurations persist across reboots
11
12## Prerequisites
13
14- Ubuntu 20.04 or later
15- User account with sudo privileges (see note below)
16- Network access to NAS
17- Internet connection for Docker installation
18
19### Sudo Access Required
20
21The installation user must be in the sudoers group. If you're not sure, check with:
22```bash
23groups | grep -q sudo && echo "You have sudo access" || echo "You need sudo access"
24```
25
26To add a user to the sudo group:
27```bash
28sudo usermod -aG sudo username
29```
30Then log out and log back in for the changes to take effect.
31
32## Quick Start
33
34### Option 1: One-line Installation (Recommended)
35
36Run this command on your Ubuntu machine:
37
38```bash
39curl -fsSL "https://tangled.sh/dynamicalsystem.com/machine/raw/main/install.sh?$(date +%s)" | bash
40```
41
42Or with custom installation directory:
43
44```bash
45curl -fsSL "https://tangled.sh/dynamicalsystem.com/machine/raw/main/install.sh?$(date +%s)" | INSTALL_DIR=/path/to/install bash
46```
47
48### Option 2: Git Clone (Requires SSH access)
49
50If you have SSH access to the git repository:
51
52```bash
53curl -fsSL "https://tangled.sh/dynamicalsystem.com/machine/raw/main/install.sh?$(date +%s)" | USE_GIT=true bash
54```
55
56Or manually:
57
58```bash
59git clone git@tangled.sh:dynamicalsystem.com/machine ~/.local/opt/dynamicalsystem.machine
60cd ~/.local/opt/dynamicalsystem.machine
61```
62
63### Run the Setup
64
65Run the setup script:
66```bash
67cd ~/.local/opt/dynamicalsystem.machine
68./setup.sh
69```
70
71## Integration with tinsnip
72
73For centralized identity management and shared infrastructure services, install [tinsnip](https://github.com/dynamicalsystem/tinsnip) first:
74
75```bash
76# 1. Install tinsnip (provides LDAP and infrastructure)
77curl -fsSL "https://tangled.sh/dynamicalsystem.com/tinsnip/raw/main/install.sh?$(date +%s)" | bash
78cd ~/.local/opt/dynamicalsystem.tinsnip && ./setup.sh
79
80# 2. Install machine (will detect and integrate with tinsnip)
81curl -fsSL "https://tangled.sh/dynamicalsystem.com/machine/raw/main/install.sh?$(date +%s)" | bash
82cd ~/.local/opt/dynamicalsystem.machine && ./setup.sh
83```
84
85Benefits of tinsnip integration:
86- **Unified Identity**: Same users and UIDs across all systems
87- **NFS Permissions**: Proper file ownership with rootless Docker
88- **Service Dependencies**: Machine services wait for infrastructure to be ready
89
90See [docs/tinsnip-integration.md](docs/tinsnip-integration.md) for detailed integration guide.
91
92### Setup Process
93
94Follow the interactive prompts to:
95- Configure NAS connection (CIFS/SMB or NFS)
96- Set up environment variables
97- Install rootless Docker
98
99After completion, log out and log back in for all changes to take effect
100
101## Individual Components
102
103You can run individual scripts if needed:
104
105```bash
106# Mount NAS only
107./scripts/mount_nas.sh
108
109# Install Docker only
110./scripts/install_docker.sh
111
112# Configure environment variables
113./scripts/manage_env.sh
114
115# Set up boot services
116./scripts/configure_boot.sh
117```
118
119## Environment Variables
120
121The system manages environment variables through a `.env` file stored on the NAS mount. If the file doesn't exist, you'll be prompted to create it with these variables:
122
123- `DYNAMICAL_SYSTEM_FOLDER`: Where config, secrets and data are
124- `DYNAMICAL_SYSTEM_ENV`: Environment (prod/test/dev)
125
126Variables are:
127- Loaded automatically on login via `/etc/profile.d/machine-env.sh`
128- Available system-wide through systemd services
129- Stored securely with 600 permissions
130
131## NAS Mount Configuration
132
133### CIFS/SMB
134Credentials are stored in `/etc/samba/credentials-<share>` with secure permissions. The mount is configured in `/etc/fstab` for persistence.
135
136### NFS
137Standard NFS mount configuration in `/etc/fstab` with appropriate options for reliability.
138
139## Docker Configuration
140
141Rootless Docker is installed with:
142- User namespace isolation using the concept of `sheets`
143- Non-root daemon operation
144- Automatic startup via systemd user services
145- Docker Compose plugin included
146- Pasta networking backend (if available) for improved connectivity
147
148### Known Limitations
149
150**Rootless Docker Networking**:
151- Container outbound connectivity may be limited in rootless mode
152- If you experience issues pulling images or containers can't reach the internet:
153 - Try using `docker run --network host` for containers that need network access
154 - Consider using rootful Docker with `sudo docker` for full network capabilities
155 - On networks with IPv4 restrictions, pasta backend provides better connectivity than slirp4netns
156
157## Boot Services
158
159The following systemd services are created:
160- `machine-env-loader.service`: Loads environment variables at boot
161- `verify-nas-mount.service`: Ensures NAS is mounted before loading env vars
162- `docker-rootless.service`: Starts Docker in user context
163- `machine-startup.service`: Handles overall boot initialization
164
165## Troubleshooting
166
167### NAS Mount Issues
168```bash
169# Check mount status
170mount | grep <mount_point>
171
172# Verify fstab entry
173cat /etc/fstab
174
175# Test mount manually
176sudo mount <mount_point>
177```
178
179### Docker Issues
180```bash
181# Check Docker status
182systemctl --user status docker
183
184# Verify Docker context
185docker context ls
186
187# Test Docker
188docker run hello-world
189```
190
191### Environment Variables
192```bash
193# Check loaded variables
194env | grep <VAR_NAME>
195
196# Verify .env file
197cat <nas_mount>/.env
198
199# Check profile script
200cat /etc/profile.d/machine-env.sh
201```
202
203## Security Notes
204
205- NAS credentials are stored with 600 permissions
206- Docker runs in rootless mode for enhanced security
207- Environment variables containing secrets are handled securely
208- All scripts validate inputs and check prerequisites
209
210## Logs
211
212Setup logs are saved to `/tmp/machine-setup-<timestamp>.log`
213
214## License
215
216This project is provided as-is for automation purposes.