|
1 | | -files downloaded during build process will be put here |
| 1 | +# DT4CC Tango Container Setup and Usage Guide |
| 2 | + |
| 3 | +This guide provides step-by-step instructions for running the DT4CC Tango containers with MySQL database and Tango DataBaseDS. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Docker and Docker Compose installed on your system |
| 8 | +- Local MySQL/MariaDB service should be **stopped** to avoid port conflicts |
| 9 | + |
| 10 | +## Quick Start |
| 11 | + |
| 12 | +### 1. Stop Local Database Services |
| 13 | + |
| 14 | +Before starting the containers, ensure your local MySQL or MariaDB service is stopped to avoid port conflicts: |
| 15 | + |
| 16 | +**On macOS:** |
| 17 | +```bash |
| 18 | +# Stop MySQL if running via Homebrew |
| 19 | +brew services stop mysql |
| 20 | + |
| 21 | +# Or stop MariaDB |
| 22 | +brew services stop mariadb |
| 23 | +``` |
| 24 | + |
| 25 | +**On Linux:** |
| 26 | +```bash |
| 27 | +# Stop MySQL |
| 28 | +sudo systemctl stop mysql |
| 29 | +# or |
| 30 | +sudo systemctl stop mariadb |
| 31 | +``` |
| 32 | + |
| 33 | +**On Windows:** |
| 34 | +- Stop MySQL/MariaDB service from Services management console |
| 35 | + |
| 36 | +### 2. Start the Database and Tango DataBaseDS |
| 37 | + |
| 38 | +Navigate to the `tango-mysql` directory and start the database services: |
| 39 | + |
| 40 | +```bash |
| 41 | +cd tango-mysql |
| 42 | +docker compose up -d |
| 43 | +``` |
| 44 | + |
| 45 | +This will start: |
| 46 | +- MySQL 8.0 database on port 3306 |
| 47 | +- Tango DataBaseDS on port 10000 |
| 48 | +- Both services will be connected via the `tango-net` network |
| 49 | + |
| 50 | +Wait for the services to be healthy (check with `docker compose ps`). |
| 51 | + |
| 52 | +### 3. Build and Start the Application Container |
| 53 | + |
| 54 | +Return to the main directory and build the application container: |
| 55 | + |
| 56 | +```bash |
| 57 | +cd .. |
| 58 | +docker compose -f docker-compose.app.yml build |
| 59 | +docker compose -f docker-compose.app.yml up -d |
| 60 | +``` |
| 61 | + |
| 62 | +This will: |
| 63 | +- Build the application container with Conda environment `tangoenv1` |
| 64 | +- Install all required Python packages and dependencies |
| 65 | +- Clone and install the required repositories (lat2db, bact-device-models, bact-twin-architecture, dt4acc) |
| 66 | + |
| 67 | +### 4. Start the Tango Server |
| 68 | + |
| 69 | +Access the application container and start the Tango server: |
| 70 | + |
| 71 | +```bash |
| 72 | +docker exec -it tango_app bash |
| 73 | +``` |
| 74 | + |
| 75 | +Inside the container, activate the Conda environment and start the server: |
| 76 | + |
| 77 | +```bash |
| 78 | +conda activate tangoenv1 |
| 79 | +cd /opt/dt4acc |
| 80 | +python scripts/dt4acc_enhanced_tango.py |
| 81 | +``` |
| 82 | + |
| 83 | +You should see server startup messages and confirmation that the Tango server is running. |
| 84 | + |
| 85 | +## Testing the Setup |
| 86 | + |
| 87 | +### Basic Device Testing |
| 88 | + |
| 89 | +Open a **new terminal** and access the container again: |
| 90 | + |
| 91 | +```bash |
| 92 | +docker exec -it tango_app bash |
| 93 | +conda activate tangoenv1 |
| 94 | +``` |
| 95 | + |
| 96 | +Test basic device connectivity: |
| 97 | + |
| 98 | +```python |
| 99 | +python |
| 100 | +``` |
| 101 | + |
| 102 | +In the Python shell: |
| 103 | + |
| 104 | +```python |
| 105 | +from tango import DeviceProxy |
| 106 | + |
| 107 | +# Test power converter device |
| 108 | +dev = DeviceProxy("SimpleTangoServer/test/power_converter_Q3P2T6R") |
| 109 | +dev.current_setpoint = 5.1 |
| 110 | + |
| 111 | +# You should see logs showing twiss and orbit calculations |
| 112 | +``` |
| 113 | + |
| 114 | +### Using Test Scripts |
| 115 | + |
| 116 | +Navigate to the test examples directory: |
| 117 | + |
| 118 | +```bash |
| 119 | +cd /opt/dt4acc/tests/example |
| 120 | +``` |
| 121 | + |
| 122 | +#### Available Test Scripts |
| 123 | + |
| 124 | +1. **Check Device Status:** |
| 125 | + ```bash |
| 126 | + python check_device_status.py SimpleTangoServer/test/magnet_VS3M2T8R |
| 127 | + ``` |
| 128 | + |
| 129 | +2. **Show Device Values:** |
| 130 | + ```bash |
| 131 | + python show_device_values.py SimpleTangoServer/test/power_converter_Q3P2T1R |
| 132 | + ``` |
| 133 | + |
| 134 | +3. **List All Devices:** |
| 135 | + ```bash |
| 136 | + python list_all_devices.py |
| 137 | + ``` |
| 138 | + |
| 139 | +4. **List All Servers:** |
| 140 | + ```bash |
| 141 | + python list_all_servers.py |
| 142 | + ``` |
| 143 | + |
| 144 | +5. **Update Device Value:** |
| 145 | + ```bash |
| 146 | + python update_device_value.py <device_name> <attribute> <value> |
| 147 | + ``` |
| 148 | + |
| 149 | +6. **Check Mapped Properties:** |
| 150 | + ```bash |
| 151 | + python check_mapped_properties.py <device_name> |
| 152 | + ``` |
| 153 | + |
| 154 | +## Container Management |
| 155 | + |
| 156 | +### View Running Containers |
| 157 | +```bash |
| 158 | +docker ps |
| 159 | +``` |
| 160 | + |
| 161 | +### View Container Logs |
| 162 | +```bash |
| 163 | +# Application container logs |
| 164 | +docker logs tango_app |
| 165 | + |
| 166 | +# Database logs |
| 167 | +docker logs tango-mysql-mysql-1 |
| 168 | + |
| 169 | +# DataBaseDS logs |
| 170 | +docker logs tango-mysql-databaseds-1 |
| 171 | +``` |
| 172 | + |
| 173 | +### Stop All Services |
| 174 | +```bash |
| 175 | +# Stop application container |
| 176 | +docker compose -f docker-compose.app.yml down |
| 177 | + |
| 178 | +# Stop database services |
| 179 | +cd tango-mysql |
| 180 | +docker compose down |
| 181 | +``` |
| 182 | + |
| 183 | +### Restart Services |
| 184 | +```bash |
| 185 | +# Restart database services |
| 186 | +cd tango-mysql |
| 187 | +docker compose restart |
| 188 | + |
| 189 | +# Restart application container |
| 190 | +cd .. |
| 191 | +docker compose -f docker-compose.app.yml restart |
| 192 | +``` |
| 193 | + |
| 194 | +## Troubleshooting |
| 195 | + |
| 196 | +### Port Conflicts |
| 197 | +If you encounter port conflicts: |
| 198 | +- Ensure local MySQL/MariaDB is stopped |
| 199 | +- Check if ports 3306 or 10000 are already in use: `lsof -i :3306` or `lsof -i :10000` |
| 200 | + |
| 201 | + |
| 202 | + |
| 203 | +### Tango Server Issues |
| 204 | +If the Tango server doesn't start: |
| 205 | +1. Check that DataBaseDS is running and healthy |
| 206 | +2. Verify the TANGO_HOST environment variable |
| 207 | +3. Check the server logs for specific error messages |
| 208 | + |
| 209 | +## Environment Details |
| 210 | + |
| 211 | +- **Conda Environment:** `tangoenv1` |
| 212 | +- **Database:** MySQL 8.0 |
| 213 | +- **Tango DataBaseDS:** |
| 214 | +- **Application:** DT4CC with enhanced Tango integration |
| 215 | + |
| 216 | + |
| 217 | +## File Structure |
| 218 | + |
| 219 | +``` |
| 220 | +dt4cc-tango/ |
| 221 | +├── docker-compose.yml # Full stack (DB + App) |
| 222 | +├── docker-compose.app.yml # App only (requires external DB) |
| 223 | +├── Dockerfile.app # Application container definition |
| 224 | +├── tango.yaml # Conda environment specification |
| 225 | +├── tango-mysql/ |
| 226 | +│ ├── compose.yaml # Database services |
| 227 | +│ └── init/ # SQL initialization scripts |
| 228 | +└── README.md # This guide |
| 229 | +``` |
| 230 | + |
| 231 | + |
0 commit comments